@ansonlai/docx-redline-js 0.4.0 → 0.5.0

package/node/cli.js

@@ -0,0 +1,317 @@
+import { access, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { openDocx } from './docx-document.js';
+import { MemoryZip, unzipDocx } from './zip-archive.js';
+import { validateDocxPackage } from '../services/standalone-docx-plumbing.js';
+import { validateRedlineOoxml } from '../core/redline-validation.js';
+import { configureLogger } from '../adapters/logger.js';
+
+const suffixes = { apply: 'redlined', accept: 'accepted', reject: 'rejected', 'delete-comments': 'comments-removed' };
+const CLI_CONTRACT_VERSION = 2;
+const CLI_CAPABILITIES = [
+    'atomic-batch-results-on-package-failure',
+    'baseline-aware-validation',
+    'document-scoped-list-revision-ids'
+];
+const commandOptions = {
+    version: new Set(['help']),
+    inspect: new Set(['help', 'search', 'revised', 'table', 'body', 'nonEmpty', 'index', 'indexes', 'range', 'view']),
+    extract: new Set(['help', 'search', 'revised', 'table', 'body', 'nonEmpty', 'index', 'indexes', 'range', 'view']),
+    preflight: new Set(['help', 'operations', 'author', 'strictTargets', 'target', 'modified', 'comment', 'textToComment', 'targetRef', 'existingRevisions']),
+    apply: new Set(['help', 'operations', 'author', 'output', 'inPlace', 'force', 'noOverwrite', 'noClobber', 'expectedRevision', 'target', 'modified', 'comment', 'textToComment', 'targetRef', 'existingRevisions', 'atomic', 'generateRedlines', 'noRedlines']),
+    accept: new Set(['help', 'author', 'allAuthors', 'output', 'inPlace', 'force', 'noOverwrite', 'noClobber']),
+    reject: new Set(['help', 'author', 'allAuthors', 'output', 'inPlace', 'force', 'noOverwrite', 'noClobber']),
+    'delete-comments': new Set(['help', 'author', 'allAuthors', 'output', 'inPlace', 'force', 'noOverwrite', 'noClobber']),
+    validate: new Set(['help', 'baseline'])
+};
+
+function cliError(code, message, exitCode = 2, details) { return { status: 'error', error: { code, message, ...(details ? { details } : {}) }, exitCode }; }
+const optionAliases = new Map([
+    ['operationsFile', 'operations'],
+    ['o', 'output'],
+    ['a', 'author'],
+    ['i', 'inPlace'],
+    ['f', 'force'],
+    ['h', 'help'],
+    ['no-overwrite', 'noOverwrite'],
+    ['no-clobber', 'noClobber'],
+    ['no-redlines', 'noRedlines'],
+    ['generate-redlines', 'generateRedlines']
+]);
+function parseArgs(argv) {
+    const positionals = []; const flags = {};
+    for (let index = 0; index < argv.length; index++) {
+        const token = argv[index];
+        if (!token.startsWith('-') || token === '-') { positionals.push(token); continue; }
+        const prefixLength = token.startsWith('--') ? 2 : 1;
+        const [rawKey, inline] = token.slice(prefixLength).split(/=(.*)/s);
+        const normalizedKey = rawKey.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+        const key = optionAliases.get(normalizedKey) || normalizedKey;
+        if (inline !== undefined) flags[key] = inline;
+        else if (argv[index + 1] && (!argv[index + 1].startsWith('-') || /^-\d/.test(argv[index + 1]))) flags[key] = argv[++index];
+        else flags[key] = true;
+    }
+    return { command: positionals[0], input: positionals[1], extraPositionals: positionals.slice(2), flags };
+}
+function positiveInteger(value) {
+    const text = String(value).trim();
+    const parsed = /^\d+$/.test(text) ? Number(text) : null;
+    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : null;
+}
+function invalidFilter(message) {
+    const error = new Error(message);
+    error.code = 'INVALID_FILTER';
+    return error;
+}
+function parseIndexes(value) {
+    const tokens = String(value).split(',');
+    if (!tokens.length || tokens.some(token => positiveInteger(token) == null)) {
+        throw invalidFilter('--indexes must be a comma-separated list of positive 1-based integers.');
+    }
+    return tokens.map(positiveInteger);
+}
+function parseRange(value) {
+    const match = String(value).match(/^\s*(\d+)\s*([:,\-])\s*(\d+)\s*$/);
+    if (!match) throw invalidFilter('--range must use START:END with positive 1-based integers.');
+    const start = positiveInteger(match[1]);
+    const end = positiveInteger(match[3]);
+    if (start == null || end == null || end < start) {
+        throw invalidFilter('--range must have positive 1-based endpoints with END greater than or equal to START.');
+    }
+    return { start, end };
+}
+function validateCommandOptions(command, flags, extraPositionals) {
+    if (extraPositionals.length > 0) return cliError('UNEXPECTED_ARGUMENT', `Unexpected argument: ${extraPositionals[0]}`);
+    const allowed = commandOptions[command];
+    const unknown = Object.keys(flags).find(option => !allowed.has(option));
+    return unknown ? cliError('UNKNOWN_OPTION', `Unknown option for ${command}: --${unknown.replace(/[A-Z]/g, letter => `-${letter.toLowerCase()}`)}`) : null;
+}
+function inspectionOptions(flags) {
+    const options = {};
+    if (flags.search) options.search = flags.search;
+    if (flags.revised) options.revisedOnly = true;
+    if (flags.table) options.inTable = true;
+    if (flags.body) options.inTable = false;
+    if (flags.nonEmpty) options.skipEmpty = true;
+    const selectors = ['index', 'indexes', 'range'].filter(name => flags[name] !== undefined);
+    if (selectors.length > 1) throw invalidFilter('Use only one of --index, --indexes, or --range.');
+    if (flags.index !== undefined) {
+        const index = positiveInteger(flags.index);
+        if (index == null) throw invalidFilter('--index must be a positive 1-based integer.');
+        options.indexes = [index];
+    }
+    if (flags.indexes !== undefined) options.indexes = parseIndexes(flags.indexes);
+    if (flags.range !== undefined) options.range = parseRange(flags.range);
+    if (flags.view) {
+        if (!['accepted', 'rejected', 'current'].includes(String(flags.view))) {
+            throw invalidFilter('--view must be accepted, rejected, or current.');
+        }
+        options.revisionView = flags.view;
+    }
+    return options;
+}
+async function readOperations(file, flags = {}) {
+    if (!file && flags?.target) {
+        let op;
+        if (flags.comment) {
+            op = {
+                type: 'comment',
+                target: String(flags.target),
+                commentContent: String(flags.comment),
+                ...(flags.textToComment ? { textToComment: String(flags.textToComment) } : {}),
+                ...(flags.targetRef ? { targetRef: positiveInteger(flags.targetRef) } : {}),
+                ...(flags.author ? { author: String(flags.author) } : {})
+            };
+        } else {
+            op = {
+                type: 'replace',
+                target: String(flags.target),
+                modified: flags.modified !== undefined ? String(flags.modified) : '',
+                ...(flags.targetRef ? { targetRef: positiveInteger(flags.targetRef) } : {}),
+                ...(flags.author ? { author: String(flags.author) } : {}),
+                ...(flags.existingRevisions ? { existingRevisions: String(flags.existingRevisions) } : {})
+            };
+        }
+        return { operations: [op], expectedRevision: null };
+    }
+    if (!file) throw Object.assign(new Error('Use --operations <file.json> or --target <text>.'), { code: 'OPERATIONS_REQUIRED' });
+    let parsed; try { parsed = JSON.parse(await readFile(file, 'utf8')); } catch (error) { throw Object.assign(new Error(`Could not read operations JSON: ${error.message}`), { code: 'INVALID_OPERATIONS_FILE' }); }
+    const operations = Array.isArray(parsed) ? parsed : (parsed?.operations || parsed?.changes);
+    if (!Array.isArray(operations)) throw Object.assign(new Error('Operations JSON must be an array or an object with an operations or changes array.'), { code: 'INVALID_OPERATIONS_FILE' });
+    return { operations, expectedRevision: parsed?.expectedRevision || null };
+}
+function outputPath(command, input, flags) {
+    if (flags.inPlace) return input;
+    if (flags.output) return path.resolve(String(flags.output));
+    const parsed = path.parse(input); return path.join(parsed.dir, `${parsed.name}.${suffixes[command]}${parsed.ext || '.docx'}`);
+}
+async function writeMutation(command, input, flags, result) {
+    if (!result.written) return { status: result.status || 'ok', ...result, outputPath: null };
+    const destination = outputPath(command, input, flags);
+    const protectExisting = Boolean(flags.noOverwrite || flags.noClobber) && !flags.force;
+    if (!flags.inPlace && protectExisting) {
+        try {
+            await access(destination);
+            throw Object.assign(new Error(`Output already exists: ${destination}`), { code: 'OUTPUT_EXISTS' });
+        } catch (error) {
+            if (error.code !== 'ENOENT') throw error;
+        }
+    }
+    await writeFile(destination, result.toBuffer());
+    return { status: result.status || 'ok', ...result, outputPath: destination };
+}
+function serializable(value) {
+    const { buffer: _buffer, toBuffer: _toBuffer, ...rest } = value || {};
+    return rest;
+}
+
+async function collectValidationIssues(buffer) {
+    const entries = unzipDocx(buffer);
+    const documentXml = entries.get('word/document.xml')?.toString('utf8') || '';
+    const revision = validateRedlineOoxml(documentXml);
+    const issues = revision.issues.map(issue => ({ source: 'word/document.xml', ...issue }));
+    try {
+        await validateDocxPackage(new MemoryZip(entries));
+    } catch (error) {
+        issues.push({ source: 'package', code: 'PACKAGE_VALIDATION', severity: 'error', message: error.message });
+    }
+    return issues;
+}
+
+function validationIssueKey(issue) {
+    return `${issue.source || ''}:${issue.code}:${issue.message}`;
+}
+
+function subtractValidationIssues(issues, baselineIssues) {
+    const remainingBaseline = new Map();
+    for (const issue of baselineIssues) {
+        const key = validationIssueKey(issue);
+        remainingBaseline.set(key, (remainingBaseline.get(key) || 0) + 1);
+    }
+    return issues.filter(issue => {
+        const key = validationIssueKey(issue);
+        const remaining = remainingBaseline.get(key) || 0;
+        if (remaining === 0) return true;
+        remainingBaseline.set(key, remaining - 1);
+        return false;
+    });
+}
+
+export async function executeCli(argv) {
+    const { command, input: rawInput, extraPositionals, flags } = parseArgs(argv);
+    if (command === 'help' || flags.help) return { status: 'ok', command: 'help', usage: 'docx-redline <version|inspect|extract|preflight|apply|accept|reject|delete-comments|validate> [file.docx] [options]' };
+    if (!command) return cliError('COMMAND_REQUIRED', 'A command is required.');
+    if (!['version','inspect','extract','preflight','apply','accept','reject','delete-comments','validate'].includes(command)) return cliError('UNKNOWN_COMMAND', `Unknown command: ${command}`);
+    if (command === 'version') {
+        if (rawInput || extraPositionals.length > 0) return cliError('UNEXPECTED_ARGUMENT', `Unexpected argument: ${rawInput || extraPositionals[0]}`);
+        const optionError = validateCommandOptions(command, flags, []);
+        if (optionError) return optionError;
+        return {
+            status: 'ok',
+            command,
+            contractVersion: CLI_CONTRACT_VERSION,
+            capabilities: CLI_CAPABILITIES
+        };
+    }
+    if (!rawInput) return cliError('INPUT_REQUIRED', 'An input .docx path is required.');
+    const optionError = validateCommandOptions(command, flags, extraPositionals);
+    if (optionError) return optionError;
+    let inspectOptions = null;
+    if (command === 'inspect' || command === 'extract') {
+        try { inspectOptions = inspectionOptions(flags); }
+        catch (error) { return cliError(error.code || 'INVALID_FILTER', error.message); }
+    }
+    const input = path.resolve(rawInput);
+    let buffer; try { buffer = await readFile(input); } catch (error) { return cliError('INPUT_READ_FAILED', error.message); }
+    try {
+        const document = openDocx(buffer);
+        if (command === 'inspect') return { ...document.inspect(inspectOptions), command, input, indexBase: 1 };
+        if (command === 'extract') {
+            const inspected = document.inspect(inspectOptions);
+            return { status: inspected.status, command, input, indexBase: 1, paragraphs: inspected.paragraphs.map(({ index, ref, paragraphId, fingerprint, exactText, inTable, list, nearestHeading }) => ({ index, ref, paragraphId, fingerprint, exactText, inTable, list, nearestHeading })), warnings: inspected.warnings };
+        }
+        if (command === 'validate') {
+            const issues = await collectValidationIssues(buffer);
+            if (flags.baseline) {
+                const baseline = path.resolve(String(flags.baseline));
+                let baselineBuffer;
+                try { baselineBuffer = await readFile(baseline); }
+                catch (error) { return cliError('BASELINE_READ_FAILED', error.message); }
+                const baselineIssues = await collectValidationIssues(baselineBuffer);
+                const introducedIssues = subtractValidationIssues(issues, baselineIssues);
+                const hasIntroducedErrors = introducedIssues.some(issue => issue.severity === 'error');
+                return {
+                    status: hasIntroducedErrors ? 'error' : 'ok',
+                    command,
+                    input,
+                    baseline,
+                    valid: !hasIntroducedErrors,
+                    issues,
+                    baselineIssues,
+                    introducedIssues
+                };
+            }
+            const hasErrors = issues.some(issue => issue.severity === 'error');
+            return { status: hasErrors ? 'error' : 'ok', command, input, valid: !hasErrors, issues };
+        }
+        const opsData = command === 'preflight' || command === 'apply' ? await readOperations(flags.operations, flags) : null;
+        const operations = opsData?.operations || null;
+        let expectedRevision = opsData?.expectedRevision || null;
+        if (flags.expectedRevision) {
+            if (typeof flags.expectedRevision === 'string') {
+                try {
+                    expectedRevision = JSON.parse(flags.expectedRevision);
+                } catch {
+                    expectedRevision = {
+                        algorithm: 'sha256',
+                        version: 1,
+                        scope: 'package',
+                        value: flags.expectedRevision.trim()
+                    };
+                }
+            } else if (typeof flags.expectedRevision === 'object') {
+                expectedRevision = flags.expectedRevision;
+            }
+        }
+        if (command === 'preflight') return {
+            ...document.preflight(operations, flags.author, {
+                strictTargets: flags.strictTargets !== 'false',
+                ...(flags.existingRevisions ? { existingRevisions: flags.existingRevisions } : {})
+            }),
+            command,
+            input
+        };
+        if (command === 'apply') {
+            const author = flags.author || process.env.DOCX_REDLINE_AUTHOR || 'AI Redliner';
+            const generateRedlines = flags.generateRedlines !== undefined
+                ? (flags.generateRedlines !== 'false' && flags.generateRedlines !== false)
+                : (!flags.noRedlines);
+            const result = await document.applyOperations(operations, {
+                author,
+                atomic: flags.atomic === true || flags.atomic === 'true',
+                validate: true,
+                strictTargets: true,
+                generateRedlines,
+                ...(flags.existingRevisions ? { existingRevisions: flags.existingRevisions } : {}),
+                ...(expectedRevision ? { expectedRevision } : {})
+            });
+            const mutationResult = await writeMutation(command, input, flags, result);
+            return {
+                command,
+                input,
+                ...serializable(mutationResult),
+                ...(result.status === 'error' || result.error ? { exitCode: 2 } : {})
+            };
+        }
+        const filter = flags.allAuthors ? { allAuthors: true } : flags.author ? { author: String(flags.author) } : null;
+        if (!filter) return cliError('AUTHOR_REQUIRED', 'Use --author <name> or --all-authors.');
+        const result = command === 'delete-comments' ? await document.deleteComments(filter) : await document.resolveRevisions(command, filter);
+        return { command, input, ...serializable(await writeMutation(command, input, flags, result)) };
+    } catch (error) { return cliError(error.code || 'CLI_FAILED', error.message); }
+}
+
+export async function runCli(argv = process.argv.slice(2), io = process) {
+    configureLogger({}, { level: 'silent' });
+    const result = await executeCli(argv); io.stdout.write(`${JSON.stringify(serializable(result), null, 2)}\n`);
+    return result.status === 'error' ? (result.exitCode || 1) : 0;
+}

package/node/docx-document.js

@@ -0,0 +1,302 @@
+import { DOMParser, XMLSerializer } from '@xmldom/xmldom';
+import { configureXmlProvider } from '../adapters/xml-adapter.js';
+import { getDefaultAuthor } from '../adapters/config.js';
+import { inspectDocumentParts } from '../services/document-inspection.js';
+import { applyOperationsToDocumentXml, preflightOperations } from '../services/standalone-operation-runner.js';
+import { createDynamicNumberingIdState, mergeNumberingXmlBySchemaOrder } from '../services/numbering-helpers.js';
+import { ensureCommentsArtifactsInZip, ensureCommentsExtendedArtifactsInZip, ensureNumberingArtifactsInZip, validateDocxPackage } from '../services/standalone-docx-plumbing.js';
+import { validateRedlineOoxml } from '../core/redline-validation.js';
+import { acceptTrackedChangesInOoxml, rejectTrackedChangesInOoxml, deleteCommentsByAuthorInOoxml } from '../services/revision-comment-management.js';
+import { createSerializer, parseOoxmlSafe } from '../adapters/xml-adapter.js';
+import { createHash } from 'node:crypto';
+import { MemoryZip, unzipDocx, zipDocx } from './zip-archive.js';
+import { computeRevisionTokenSync, validateRevisionToken, areRevisionTokensEqual } from '../services/revision-token.js';
+
+configureXmlProvider({ DOMParser, XMLSerializer });
+const text = (entries, path) => entries.get(path)?.toString('utf8') || null;
+const cloneEntries = entries => new Map([...entries].map(([name, data]) => [name, Buffer.from(data)]));
+
+/**
+ * Computes a package-scoped revision token over all uncompressed entries in a DOCX archive.
+ *
+ * @param {Buffer|Uint8Array|Map<string, Buffer>|DocxDocument|object} input
+ * @returns {{ algorithm: 'sha256', version: number, scope: 'package', value: string, coveredParts: string[] }}
+ */
+export function computePackageRevisionToken(input) {
+    let entries;
+    if (Buffer.isBuffer(input) || input instanceof Uint8Array) {
+        entries = unzipDocx(input);
+    } else if (input instanceof Map) {
+        entries = input;
+    } else if (input?.entries instanceof Map) {
+        entries = input.entries;
+    } else if (typeof input?.toBuffer === 'function') {
+        entries = unzipDocx(input.toBuffer());
+    } else {
+        throw new TypeError('computePackageRevisionToken requires a Buffer, Uint8Array, Map of entries, or DocxDocument.');
+    }
+    return computeRevisionTokenSync({
+        scope: 'package',
+        entries,
+        digestFn: bytes => createHash('sha256').update(bytes).digest('hex')
+    });
+}
+
+function nextCommentId(entries) {
+    const ids = `${text(entries, 'word/document.xml') || ''} ${text(entries, 'word/comments.xml') || ''}`.match(/(?:w:)?id=["'](\d+)["']/g) || [];
+    let next = ids.reduce((max, token) => Math.max(max, Number(token.match(/\d+/)?.[0] || 0)), 0) + 1;
+    return () => next++;
+}
+
+function existingCommentDetails(entries) {
+    const commentsXml = text(entries, 'word/comments.xml');
+    if (!commentsXml) return {};
+    const parsed = parseOoxmlSafe(commentsXml, 'application/xml');
+    if (!parsed.doc || parsed.error) return {};
+    const details = {};
+    for (const comment of Array.from(parsed.doc.getElementsByTagNameNS('*', 'comment'))) {
+        const id = comment.getAttribute('w:id') || comment.getAttribute('id');
+        if (id === '') continue;
+        details[id] = {
+            id,
+            author: comment.getAttribute('w:author') || comment.getAttribute('author') || '',
+            text: String(comment.textContent || '').trim(),
+            paraId: Array.from(comment.getElementsByTagNameNS('*', 'p'))[0]?.getAttribute('w14:paraId') || null
+        };
+    }
+    return details;
+}
+
+export class DocxDocument {
+    constructor(buffer) { this.originalBuffer = Buffer.from(buffer); this.entries = unzipDocx(this.originalBuffer); }
+    inspect(options = {}) {
+        const digestFn = options.digestFn || (bytes => createHash('sha256').update(bytes).digest('hex'));
+        return inspectDocumentParts({
+            documentXml: text(this.entries, 'word/document.xml'),
+            commentsXml: text(this.entries, 'word/comments.xml'),
+            commentsExtendedXml: text(this.entries, 'word/commentsExtended.xml'),
+            numberingXml: text(this.entries, 'word/numbering.xml'),
+            stylesXml: text(this.entries, 'word/styles.xml')
+        }, { ...options, digestFn });
+    }
+    getRevisionToken() { return computePackageRevisionToken(this.entries); }
+    get revisionToken() { return this.getRevisionToken(); }
+    preflight(operations, author = getDefaultAuthor(), options = {}) { return preflightOperations(text(this.entries, 'word/document.xml'), operations, author || getDefaultAuthor(), { ...options, _existingCommentDetails: existingCommentDetails(this.entries) }); }
+    toBuffer() { return zipDocx(this.entries); }
+    async applyOperations(operations, options = {}) {
+        if (options?.expectedRevision) {
+            const tokenValidation = validateRevisionToken(options.expectedRevision);
+            if (!tokenValidation.valid) {
+                return {
+                    status: 'error',
+                    hasChanges: false,
+                    written: false,
+                    rolledBack: true,
+                    results: [],
+                    artifactsChanged: [],
+                    error: {
+                        code: tokenValidation.error?.code || 'INVALID_REVISION_TOKEN',
+                        message: tokenValidation.error?.message || 'Invalid revision token.'
+                    },
+                    validation: { originalIssues: [], generatedIssues: [] },
+                    buffer: Buffer.from(this.originalBuffer),
+                    toBuffer: () => Buffer.from(this.originalBuffer)
+                };
+            }
+            if (options.expectedRevision.scope !== 'package') {
+                return {
+                    status: 'error',
+                    hasChanges: false,
+                    written: false,
+                    rolledBack: true,
+                    results: [],
+                    artifactsChanged: [],
+                    error: {
+                        code: 'REVISION_TOKEN_SCOPE_MISMATCH',
+                        message: `Revision token scope mismatch: expected 'package', got '${options.expectedRevision.scope}'.`
+                    },
+                    validation: { originalIssues: [], generatedIssues: [] },
+                    buffer: Buffer.from(this.originalBuffer),
+                    toBuffer: () => Buffer.from(this.originalBuffer)
+                };
+            }
+            const currentToken = computePackageRevisionToken(this.entries);
+            if (!areRevisionTokensEqual(currentToken.value, options.expectedRevision.value)) {
+                return {
+                    status: 'error',
+                    hasChanges: false,
+                    written: false,
+                    rolledBack: true,
+                    results: [],
+                    artifactsChanged: [],
+                    error: {
+                        code: 'REVISION_MISMATCH',
+                        message: `Document revision mismatch: expected '${options.expectedRevision.value}', current is '${currentToken.value}'.`
+                    },
+                    validation: { originalIssues: [], generatedIssues: [] },
+                    buffer: Buffer.from(this.originalBuffer),
+                    toBuffer: () => Buffer.from(this.originalBuffer)
+                };
+            }
+        }
+
+        const originalEntries = this.entries; const working = cloneEntries(originalEntries); const zip = new MemoryZip(working);
+        const documentXml = text(working, 'word/document.xml');
+        let originalIssues = [];
+        let operationResult = null;
+        try {
+            if (!documentXml) throw new Error('Missing word/document.xml.');
+            const baseline = validateRedlineOoxml(documentXml);
+            originalIssues = baseline.issues.map(issue => ({ source: 'word/document.xml', ...issue }));
+            try { await validateDocxPackage(new MemoryZip(cloneEntries(originalEntries))); }
+            catch (error) { originalIssues.push({ source: 'package', code: 'PACKAGE_VALIDATION', severity: 'error', message: error.message }); }
+            const context = {
+                numberingIdState: createDynamicNumberingIdState(text(working, 'word/numbering.xml') || undefined),
+                commentsXml: text(working, 'word/comments.xml'),
+                commentsExtendedXml: text(working, 'word/commentsExtended.xml')
+            };
+            const { expectedRevision: _pkgExpectedRevision, ...runnerOptions } = options;
+            const author = options.author || getDefaultAuthor();
+            const result = operationResult = await applyOperationsToDocumentXml(documentXml, operations, author, context, {
+                ...runnerOptions, atomic: options.atomic === true, strictTargets: options.strictTargets !== false,
+                _existingCommentDetails: existingCommentDetails(working),
+                commentIdAllocator: nextCommentId(working)
+            });
+            if (result.rolledBack || result.status === 'error') return { ...result, written: false, artifactsChanged: [], validation: { originalIssues, generatedIssues: [] }, buffer: this.originalBuffer, toBuffer: () => Buffer.from(this.originalBuffer) };
+            if (!result.hasChanges) return { ...result, status: result.status || 'ok', written: false, artifactsChanged: [], validation: { originalIssues, generatedIssues: [] }, buffer: Buffer.from(this.originalBuffer), toBuffer: () => Buffer.from(this.originalBuffer) };
+            working.set('word/document.xml', Buffer.from(result.documentXml));
+            await ensureNumberingArtifactsInZip(zip, result.numberingXmlParts, { mergeNumberingXml: mergeNumberingXmlBySchemaOrder });
+            const existingCommentsXml = text(working, 'word/comments.xml');
+            const commentsXmlForPackaging = result.commentsXml || existingCommentsXml;
+            await ensureCommentsArtifactsInZip(zip, commentsXmlForPackaging, {
+                replaceExisting: result.commentsXmlMode === 'replace' || (!result.commentsXml && !!existingCommentsXml)
+            });
+            const existingCommentsExtendedXml = text(working, 'word/commentsExtended.xml');
+            const commentsExtendedXmlForPackaging = result.commentsExtendedXml || existingCommentsExtendedXml;
+            await ensureCommentsExtendedArtifactsInZip(zip, commentsExtendedXmlForPackaging, {
+                replaceExisting: result.commentsExtendedXmlMode === 'replace' || (!result.commentsExtendedXml && !!existingCommentsExtendedXml)
+            });
+            if (options.validate !== false) {
+                const generated = validateRedlineOoxml(result.documentXml);
+                const baselineErrors = new Set(baseline.issues.filter(i => i.severity === 'error').map(i => `${i.code}:${i.message}`));
+                const introduced = generated.issues.filter(i => i.severity === 'error' && !baselineErrors.has(`${i.code}:${i.message}`));
+                if (introduced.length) {
+                    const codes = [...new Set(introduced.map(issue => issue.code))].join(', ');
+                    throw Object.assign(
+                        new Error(`Applied operations introduced invalid revision markup (${codes}); these are generated-output issues, not pre-existing input issues.`),
+                        { issues: introduced }
+                    );
+                }
+                await validateDocxPackage(zip);
+            }
+            this.entries = working;
+            const output = this.toBuffer();
+            this.originalBuffer = Buffer.from(output);
+            const artifactsChanged = [...working].filter(([name, data]) => !originalEntries.has(name) || !data.equals(originalEntries.get(name))).map(([name]) => name);
+            return { ...result, status: result.status || 'ok', written: true, artifactsChanged, validation: { originalIssues, generatedIssues: [] }, buffer: output, inspection: this.inspect(), toBuffer: () => Buffer.from(output) };
+        } catch (error) {
+            this.entries = originalEntries;
+            const generatedIssues = error.issues || [{ source: 'package', code: 'PACKAGE_OPERATION_FAILED', severity: 'error', message: error.message }];
+            return {
+                ...(operationResult ? {
+                    results: operationResult.results || [],
+                    receipts: operationResult.receipts || [],
+                    executionOrder: operationResult.executionOrder || [],
+                    authorsUsed: operationResult.authorsUsed || []
+                } : { results: [] }),
+                status: 'error',
+                hasChanges: false,
+                written: false,
+                rolledBack: true,
+                artifactsChanged: [],
+                error: { code: 'PACKAGE_OPERATION_FAILED', message: error.message },
+                validation: { originalIssues, generatedIssues },
+                issues: generatedIssues,
+                buffer: Buffer.from(this.originalBuffer),
+                toBuffer: () => Buffer.from(this.originalBuffer)
+            };
+        }
+    }
+
+    async resolveRevisions(action, options = {}) {
+        const transform = action === 'accept' ? acceptTrackedChangesInOoxml : action === 'reject' ? rejectTrackedChangesInOoxml : null;
+        if (!transform) return packageFailure(this.originalBuffer, 'INVALID_ACTION', `Unknown revision action: ${action}`);
+        const source = Buffer.from(this.originalBuffer); const working = cloneEntries(this.entries); const zip = new MemoryZip(working);
+        const result = transform(text(working, 'word/document.xml'), { author: options.author, allAuthors: options.allAuthors === true });
+        if (result.status === 'error' || result.error) return packageFailure(source, result.error?.code || 'REVISION_OPERATION_FAILED', result.error?.message || 'Revision operation failed.');
+        if (!result.hasChanges) return { ...result, status: 'ok', written: false, artifactsChanged: [], buffer: source, toBuffer: () => Buffer.from(source) };
+        working.set('word/document.xml', Buffer.from(result.oxml));
+        try { if (options.validate !== false) await validateDocxPackage(zip); }
+        catch (error) { return packageFailure(source, 'PACKAGE_VALIDATION', error.message); }
+        this.entries = working; const output = this.toBuffer(); this.originalBuffer = Buffer.from(output);
+        return { ...result, status: 'ok', written: true, artifactsChanged: ['word/document.xml'], buffer: output, toBuffer: () => Buffer.from(output) };
+    }
+
+    async deleteComments(options = {}) {
+        const source = Buffer.from(this.originalBuffer); const working = cloneEntries(this.entries); const commentsXml = text(working, 'word/comments.xml');
+        if (!commentsXml) return { status: 'ok', hasChanges: false, written: false, commentsRemoved: 0, referencesRemoved: 0, artifactsChanged: [], buffer: source, toBuffer: () => Buffer.from(source) };
+        const parsed = parseOoxmlSafe(commentsXml, 'application/xml');
+        if (!parsed.doc || parsed.error) return packageFailure(source, 'PARSE_ERROR', parsed.error?.message || 'Could not parse comments.xml.');
+        const matches = comment => options.allAuthors === true || (comment.getAttribute('w:author') || comment.getAttribute('author')) === options.author;
+        const ids = new Set(Array.from(parsed.doc.getElementsByTagNameNS('*', 'comment')).filter(matches).map(node => node.getAttribute('w:id') || node.getAttribute('id')).filter(Boolean));
+        if (!ids.size) return { status: 'ok', hasChanges: false, written: false, commentsRemoved: 0, referencesRemoved: 0, artifactsChanged: [], buffer: source, toBuffer: () => Buffer.from(source) };
+        const commentsExtendedXml = text(working, 'word/commentsExtended.xml');
+        let extendedParsed = null;
+        const removedParaIds = new Set();
+        if (commentsExtendedXml) {
+            extendedParsed = parseOoxmlSafe(commentsExtendedXml, 'application/xml');
+            if (!extendedParsed.doc || extendedParsed.error) return packageFailure(source, 'PARSE_ERROR', extendedParsed.error?.message || 'Could not parse commentsExtended.xml.');
+            const idByParaId = new Map();
+            for (const comment of Array.from(parsed.doc.getElementsByTagNameNS('*', 'comment'))) {
+                const id = comment.getAttribute('w:id') || comment.getAttribute('id');
+                const paragraph = Array.from(comment.getElementsByTagNameNS('*', 'p'))[0];
+                const paraId = paragraph?.getAttribute('w14:paraId') || paragraph?.getAttribute('paraId');
+                if (paraId) idByParaId.set(paraId.toUpperCase(), id);
+            }
+            for (const [paraId, id] of idByParaId) if (ids.has(id)) removedParaIds.add(paraId);
+            let expanded = true;
+            while (expanded) {
+                expanded = false;
+                for (const entry of Array.from(extendedParsed.doc.getElementsByTagNameNS('*', 'commentEx'))) {
+                    const paraId = (entry.getAttribute('w15:paraId') || entry.getAttribute('paraId') || '').toUpperCase();
+                    const parentParaId = (entry.getAttribute('w15:paraIdParent') || entry.getAttribute('paraIdParent') || '').toUpperCase();
+                    if (parentParaId && removedParaIds.has(parentParaId) && !removedParaIds.has(paraId)) {
+                        removedParaIds.add(paraId); if (idByParaId.has(paraId)) ids.add(idByParaId.get(paraId)); expanded = true;
+                    }
+                }
+            }
+        }
+        const commentsResult = deleteCommentsByAuthorInOoxml(commentsXml, { author: options.author, allAuthors: options.allAuthors === true });
+        const remainingParsed = parseOoxmlSafe(commentsResult.oxml, 'application/xml');
+        if (!remainingParsed.doc || remainingParsed.error) return packageFailure(source, 'PARSE_ERROR', remainingParsed.error?.message || 'Could not parse updated comments.xml.');
+        for (const comment of Array.from(remainingParsed.doc.getElementsByTagNameNS('*', 'comment'))) {
+            const id = comment.getAttribute('w:id') || comment.getAttribute('id');
+            if (ids.has(id)) comment.parentNode?.removeChild(comment);
+        }
+        const documentParsed = parseOoxmlSafe(text(working, 'word/document.xml'), 'application/xml');
+        if (!documentParsed.doc || documentParsed.error) return packageFailure(source, 'PARSE_ERROR', documentParsed.error?.message || 'Could not parse document.xml.');
+        let referencesRemoved = 0;
+        for (const name of ['commentRangeStart', 'commentRangeEnd', 'commentReference']) for (const node of Array.from(documentParsed.doc.getElementsByTagNameNS('*', name))) {
+            const id = node.getAttribute('w:id') || node.getAttribute('id'); if (!ids.has(id) || !node.parentNode) continue;
+            const parent = node.parentNode; parent.removeChild(node); referencesRemoved += 1;
+            if (name === 'commentReference' && parent.localName === 'r' && !Array.from(parent.childNodes || []).some(child => child.nodeType === 1 && child.localName !== 'rPr')) parent.parentNode?.removeChild(parent);
+        }
+        const serializer = createSerializer();
+        working.set('word/comments.xml', Buffer.from(serializer.serializeToString(remainingParsed.doc)));
+        if (extendedParsed?.doc) {
+            for (const entry of Array.from(extendedParsed.doc.getElementsByTagNameNS('*', 'commentEx'))) {
+                const paraId = (entry.getAttribute('w15:paraId') || entry.getAttribute('paraId') || '').toUpperCase();
+                if (removedParaIds.has(paraId)) entry.parentNode?.removeChild(entry);
+            }
+            working.set('word/commentsExtended.xml', Buffer.from(serializer.serializeToString(extendedParsed.doc)));
+        }
+        working.set('word/document.xml', Buffer.from(serializer.serializeToString(documentParsed.doc)));
+        try { if (options.validate !== false) await validateDocxPackage(new MemoryZip(working)); }
+        catch (error) { return packageFailure(source, 'PACKAGE_VALIDATION', error.message); }
+        this.entries = working; const output = this.toBuffer(); this.originalBuffer = Buffer.from(output);
+        return { status: 'ok', hasChanges: true, written: true, commentsRemoved: ids.size, referencesRemoved, artifactsChanged: ['word/document.xml', 'word/comments.xml', ...(extendedParsed?.doc ? ['word/commentsExtended.xml'] : [])], buffer: output, toBuffer: () => Buffer.from(output) };
+    }
+}
+
+function packageFailure(source, code, message) { return { status: 'error', hasChanges: false, written: false, rolledBack: true, error: { code, message }, artifactsChanged: [], buffer: Buffer.from(source), toBuffer: () => Buffer.from(source) }; }
+export function openDocx(input) { return new DocxDocument(input); }

package/node/index.d.ts

@@ -0,0 +1,31 @@
+import type { DocumentOperation, DocumentOperationBatchResult, OperationPreflightResult, StandaloneRunnerOptions } from '../services/standalone-operation-runner.js';
+import type { DocumentInspectionOptions, DocumentInspectionResult, RevisionToken } from '../index.js';
+
+export interface DocxApplyOptions extends StandaloneRunnerOptions {
+  author?: string;
+  validate?: boolean;
+}
+export interface DocxApplyResult extends DocumentOperationBatchResult {
+  written: boolean;
+  buffer: Uint8Array;
+  inspection?: DocumentInspectionResult;
+  artifactsChanged?: string[];
+  validation?: { originalIssues: unknown[]; generatedIssues: unknown[] };
+  issues?: unknown[];
+  toBuffer(): Uint8Array;
+}
+export class DocxDocument {
+  constructor(input: Uint8Array);
+  inspect(options?: DocumentInspectionOptions): DocumentInspectionResult;
+  getRevisionToken(): RevisionToken;
+  readonly revisionToken: RevisionToken;
+  preflight(operations: DocumentOperation[], author?: string, options?: StandaloneRunnerOptions): OperationPreflightResult;
+  applyOperations(operations: DocumentOperation[], options?: DocxApplyOptions): Promise<DocxApplyResult>;
+  resolveRevisions(action: 'accept' | 'reject', options: { author?: string; allAuthors?: boolean; validate?: boolean }): Promise<DocxApplyResult>;
+  deleteComments(options: { author?: string; allAuthors?: boolean; validate?: boolean }): Promise<DocxApplyResult>;
+  toBuffer(): Uint8Array;
+}
+export function computePackageRevisionToken(input: unknown): RevisionToken;
+export function openDocx(input: Uint8Array): DocxDocument;
+export function executeCli(argv: string[]): Promise<Record<string, unknown>>;
+export function runCli(argv?: string[], io?: { stdout: { write(value: string): unknown } }): Promise<number>;

package/node/index.js

@@ -0,0 +1,2 @@
+export { DocxDocument, openDocx, computePackageRevisionToken } from './docx-document.js';
+export { executeCli, runCli } from './cli.js';