@ansonlai/docx-redline-js 0.5.4 → 0.6.1

package/node/cli.js

@@ -6,29 +6,34 @@ import { validateDocxPackage } from '../services/standalone-docx-plumbing.js';
 import { validateRedlineOoxml } from '../core/redline-validation.js';
 import { configureLogger } from '../adapters/logger.js';
 import { isExistingRevisionsPolicy } from '../services/document-operation-contract.js';
-
-const suffixes = { apply: 'redlined', accept: 'accepted', reject: 'rejected', 'delete-comments': 'comments-removed' };
-const CLI_CONTRACT_VERSION = 3;
+import { normalizeErrorWithRecovery } from '../services/error-recovery.js';
+import { buildCliHelp, CLI_COMMANDS, commandOptionKeys } from './cli-help.js';
+
+const suffixes = { apply: 'redlined', accept: 'accepted', reject: 'rejected', 'delete-comments': 'comments-removed' };
+const CLI_CONTRACT_VERSION = 7;
+const DEFAULT_INSPECTION_LIMIT = 20;
+const INSPECTION_SOFT_BYTE_LIMIT = 48 * 1024;
 const CLI_CAPABILITIES = [
     'atomic-batch-results-on-package-failure',
     'baseline-aware-validation',
     'compact-mutation-results',
     'cross-author-revision-slicing',
-    'document-scoped-list-revision-ids'
+    'document-scoped-list-revision-ids',
+    'batch-start-source-binding',
+    'recovery-envelope-v1',
+    'require-complete-exit',
+    'operations-stdin',
+    'agent-safety-profile-v2',
+    'command-help-v1',
+    'inspection-context-v1',
+    'bounded-inspection-v1',
+    'human-document-references-v1',
+    'deduplicated-cli-receipts',
+    'compact-cli-json-v1'
 ];
-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'])
-};
+const commandOptions = Object.fromEntries(CLI_COMMANDS.map(command => [command, new Set(commandOptionKeys(command))]));
 
-function cliError(code, message, exitCode = 2, details) { return { status: 'error', error: { code, message, ...(details ? { details } : {}) }, exitCode }; }
+function cliError(code, message, exitCode = 2, details) { return { status: 'error', error: normalizeErrorWithRecovery({ code, message, ...(details ? { details } : {}) }), exitCode }; }
 const optionAliases = new Map([
     ['operationsFile', 'operations'],
     ['o', 'output'],
@@ -39,8 +44,11 @@ const optionAliases = new Map([
     ['no-overwrite', 'noOverwrite'],
     ['no-clobber', 'noClobber'],
     ['no-redlines', 'noRedlines'],
-    ['generate-redlines', 'generateRedlines']
-]);
+    ['generate-redlines', 'generateRedlines'],
+    ['require-complete', 'requireComplete'],
+    ['context', 'around'],
+    ['C', 'around']
+]);
 function parseArgs(argv) {
     const positionals = []; const flags = {};
     for (let index = 0; index < argv.length; index++) {
@@ -51,7 +59,7 @@ function parseArgs(argv) {
         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 if (argv[index + 1] && (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 };
@@ -61,11 +69,19 @@ function positiveInteger(value) {
     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 invalidFilter(message) {
+    const error = new Error(message);
+    error.code = 'INVALID_FILTER';
+    return error;
+}
+function boundedPositiveInteger(value, optionName, maximum = Number.MAX_SAFE_INTEGER) {
+    const parsed = positiveInteger(value);
+    if (parsed == null || parsed > maximum) {
+        const upperBound = maximum < Number.MAX_SAFE_INTEGER ? ` no greater than ${maximum}` : '';
+        throw invalidFilter(`${optionName} must be a positive integer${upperBound}.`);
+    }
+    return parsed;
+}
 function parseIndexes(value) {
     const tokens = String(value).split(',');
     if (!tokens.length || tokens.some(token => positiveInteger(token) == null)) {
@@ -102,10 +118,22 @@ function inspectionOptions(flags) {
         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 (flags.indexes !== undefined) options.indexes = parseIndexes(flags.indexes);
+    if (flags.range !== undefined) options.range = parseRange(flags.range);
+    if (flags.around !== undefined) {
+        const text = String(flags.around).trim();
+        if (!/^\d+$/.test(text) || Number(text) > 20) {
+            throw invalidFilter('--around must be an integer from 0 through 20.');
+        }
+        options.around = Number(text);
+        if (!flags.search) throw invalidFilter('--around requires --search.');
+    }
+    if (flags.limit !== undefined) options.limit = boundedPositiveInteger(flags.limit, '--limit', 200);
+    if (flags.after !== undefined) options.after = boundedPositiveInteger(flags.after, '--after');
+    if (flags.all && flags.limit !== undefined) throw invalidFilter('Use --all or --limit, not both.');
+    if (!flags.all && flags.limit === undefined && selectors.length === 0) options.limit = DEFAULT_INSPECTION_LIMIT;
+    if (flags.view) {
         if (!['accepted', 'rejected', 'current'].includes(String(flags.view))) {
             throw invalidFilter('--view must be accepted, rejected, or current.');
         }
@@ -113,7 +141,16 @@ function inspectionOptions(flags) {
     }
     return options;
 }
-async function readOperations(file, flags = {}) {
+async function readUtf8Stream(stream) {
+    if (!stream || typeof stream[Symbol.asyncIterator] !== 'function') {
+        throw new Error('No readable stdin stream was provided.');
+    }
+    const chunks = [];
+    for await (const chunk of stream) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+    return Buffer.concat(chunks).toString('utf8');
+}
+
+async function readOperations(file, flags = {}, stdin = process.stdin) {
     if (!file && flags?.target) {
         let op;
         if (flags.comment) {
@@ -138,7 +175,14 @@ async function readOperations(file, flags = {}) {
         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' }); }
+    let parsed;
+    try {
+        const source = file === '-' ? await readUtf8Stream(stdin) : await readFile(file, 'utf8');
+        parsed = JSON.parse(source);
+    } catch (error) {
+        const location = file === '-' ? ' from stdin' : '';
+        throw Object.assign(new Error(`Could not read operations JSON${location}: ${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 };
@@ -168,6 +212,114 @@ function serializable(value) {
     return rest;
 }
 
+function compactExtractParagraph(paragraph) {
+    const {
+        humanReference, provision, nearestHeading, index, ref, paragraphId,
+        fingerprint, revisionView, exactText, inTable, list, selectionRole,
+        contextFor
+    } = paragraph;
+    return {
+        humanReference,
+        provision,
+        nearestHeading,
+        index,
+        ref,
+        paragraphId,
+        fingerprint,
+        revisionView,
+        exactText,
+        inTable,
+        list,
+        ...(selectionRole ? { selectionRole } : {}),
+        ...(Array.isArray(contextFor) ? { contextFor } : {})
+    };
+}
+
+function inspectionResponseBytes(value) {
+    return Buffer.byteLength(JSON.stringify(value, null, 2), 'utf8') + 1;
+}
+
+function boundInspectionResponse(value, { bypass = false, broadDetailed = false } = {}) {
+    const base = {
+        ...value,
+        machineReferencesAreNotUserLocations: true,
+        ...(broadDetailed ? {
+            notes: [
+                'This detailed inspection was bounded. Prefer extract --search or an explicit --range for ordinary targeting.'
+            ]
+        } : {})
+    };
+    if (bypass) return base;
+
+    let paragraphs = [...(base.paragraphs || [])];
+    const sourceSelection = base.selection || {};
+    const totalMatches = Number.isInteger(sourceSelection.totalMatches)
+        ? sourceSelection.totalMatches
+        : paragraphs.filter(item => item.selectionRole !== 'context').length;
+    const initialReturnedMatches = Number.isInteger(sourceSelection.returnedMatches)
+        ? sourceSelection.returnedMatches
+        : paragraphs.filter(item => item.selectionRole !== 'context').length;
+    let contextTruncated = false;
+
+    const assemble = (oversizeItem = false) => {
+        const directIndexes = new Set(paragraphs
+            .filter(item => item.selectionRole !== 'context')
+            .map(item => item.index));
+        paragraphs = paragraphs
+            .map(item => item.selectionRole === 'context'
+                ? { ...item, contextFor: (item.contextFor || []).filter(index => directIndexes.has(index)) }
+                : item)
+            .filter(item => item.selectionRole !== 'context' || item.contextFor.length > 0);
+        const direct = paragraphs.filter(item => item.selectionRole !== 'context');
+        const lastDirect = direct[direct.length - 1] || null;
+        const paragraphIndexes = new Set(paragraphs.map(item => item.index));
+        const comments = Array.isArray(base.comments)
+            ? base.comments.filter(comment => paragraphIndexes.has(comment.paragraphIndex))
+            : base.comments;
+        const budgetTruncated = direct.length < initialReturnedMatches;
+        return {
+            ...base,
+            paragraphs,
+            ...(Array.isArray(base.comments) ? { comments } : {}),
+            selection: {
+                ...sourceSelection,
+                totalMatches,
+                returnedMatches: direct.length,
+                returnedParagraphs: paragraphs.length,
+                truncated: sourceSelection.truncated === true || budgetTruncated || contextTruncated,
+                nextAfter: sourceSelection.truncated === true || budgetTruncated
+                    ? (lastDirect?.index ?? sourceSelection.nextAfter ?? null)
+                    : null,
+                softByteLimit: INSPECTION_SOFT_BYTE_LIMIT,
+                oversizeItem,
+                ...(contextTruncated ? { contextTruncated: true } : {})
+            }
+        };
+    };
+
+    let result = assemble();
+    while (inspectionResponseBytes(result) > INSPECTION_SOFT_BYTE_LIMIT) {
+        const directPositions = paragraphs
+            .map((item, position) => item.selectionRole !== 'context' ? position : -1)
+            .filter(position => position >= 0);
+        if (directPositions.length > 1) {
+            paragraphs.splice(directPositions[directPositions.length - 1], 1);
+            result = assemble();
+            continue;
+        }
+        const contextPosition = paragraphs.findLastIndex(item => item.selectionRole === 'context');
+        if (contextPosition >= 0) {
+            paragraphs.splice(contextPosition, 1);
+            contextTruncated = true;
+            result = assemble();
+            continue;
+        }
+        result = assemble(true);
+        break;
+    }
+    return result;
+}
+
 function boundedText(value, limit = 512) {
     const text = String(value ?? '');
     return text.length > limit ? `${text.slice(0, limit)}…` : text;
@@ -177,7 +329,9 @@ function compactError(error) {
     if (!error || typeof error !== 'object') return error;
     const fields = [
         'code', 'stage', 'mismatchOffset', 'expectedExcerpt', 'actualExcerpt',
-        'expectedCodePoint', 'actualCodePoint', 'ownerAuthor', 'commentIds'
+        'expectedCodePoint', 'actualCodePoint', 'ownerAuthor', 'commentIds',
+        'recoveryVersion', 'category', 'field', 'captureRef', 'operationIndexes',
+        'consumedByOperation', 'expectedScope', 'actualScope'
     ];
     const compact = {};
     for (const field of fields) {
@@ -191,16 +345,68 @@ function compactError(error) {
         }));
     }
     if (Array.isArray(error.candidates)) {
-        compact.candidates = error.candidates.map(compactResolvedTarget);
+        compact.candidates = error.candidates.map(candidate => {
+            if (!candidate || typeof candidate !== 'object') return candidate;
+            const excerpt = boundedText(candidate.excerpt ?? candidate.exactText ?? candidate.text ?? '', 240);
+            return { ...compactResolvedTarget(candidate, { preserveMatchDetails: true }), ...(excerpt ? { excerpt } : {}) };
+        });
+    }
+    for (const field of ['recovery', 'issueSummary', 'expectedRevision', 'currentRevision']) {
+        if (error[field] !== undefined) compact[field] = error[field];
+    }
+    if (error.context && typeof error.context === 'object') {
+        compact.context = {
+            ...error.context,
+            ...(error.context.currentTarget ? {
+                currentTarget: {
+                    ...compactResolvedTarget(error.context.currentTarget, { preserveMatchDetails: true }),
+                    excerpt: boundedText(
+                        error.context.currentTarget.excerpt
+                            ?? error.context.currentTarget.exactText
+                            ?? error.context.currentTarget.text
+                            ?? '',
+                        240
+                    )
+                }
+            } : {})
+        };
+    }
+    if (error.sourceTarget && typeof error.sourceTarget === 'object') {
+        compact.sourceTarget = {
+            ...compactResolvedTarget(error.sourceTarget, { preserveMatchDetails: true }),
+            excerpt: boundedText(error.sourceTarget.text ?? error.sourceTarget.exactText ?? '', 240)
+        };
     }
     compact.message = boundedText(error.message || String(error));
     return compact;
 }
 
-function compactResolvedTarget(target) {
+function compactTargetTextMatch(match, preserveDetails = false) {
+    if (!match || typeof match !== 'object') return match;
+    if (preserveDetails) return match;
+    if (match.mode === 'exact') return undefined;
+    const differenceCount = Number.isInteger(match.differenceCount)
+        ? match.differenceCount
+        : (Array.isArray(match.differences) ? match.differences.length : 0);
+    return {
+        ...(match.mode ? { mode: match.mode } : {}),
+        differenceCount
+    };
+}
+
+function compactResolvedTarget(target, { preserveMatchDetails = false } = {}) {
     if (!target || typeof target !== 'object') return target;
-    const { text: _text, exactText: _exactText, ...compact } = target;
-    return compact;
+    const {
+        text: _text,
+        exactText: _exactText,
+        targetTextMatch,
+        ...compact
+    } = target;
+    const compactMatch = compactTargetTextMatch(targetTextMatch, preserveMatchDetails);
+    return {
+        ...compact,
+        ...(compactMatch ? { targetTextMatch: compactMatch } : {})
+    };
 }
 
 function compactReceipt(receipt) {
@@ -216,12 +422,13 @@ function compactReceipt(receipt) {
 
 function compactOperationResult(result) {
     if (!result || typeof result !== 'object') return result;
+    const { receipt: _receipt, ...withoutReceipt } = result;
+    const preserveMatchDetails = result.status === 'error' || !!result.error;
     return {
-        ...result,
-        ...(result.resolvedTarget ? { resolvedTarget: compactResolvedTarget(result.resolvedTarget) } : {}),
-        ...(result.resolvedAnchor ? { resolvedAnchor: compactResolvedTarget(result.resolvedAnchor) } : {}),
+        ...withoutReceipt,
+        ...(result.resolvedTarget ? { resolvedTarget: compactResolvedTarget(result.resolvedTarget, { preserveMatchDetails }) } : {}),
+        ...(result.resolvedAnchor ? { resolvedAnchor: compactResolvedTarget(result.resolvedAnchor, { preserveMatchDetails }) } : {}),
         ...(result.error ? { error: compactError(result.error) } : {}),
-        ...(result.receipt ? { receipt: compactReceipt(result.receipt) } : {}),
         ...(Array.isArray(result.warnings) ? { warnings: result.warnings.map(warning => boundedText(warning)) } : {})
     };
 }
@@ -314,11 +521,15 @@ function subtractValidationIssues(issues, baselineIssues) {
     });
 }
 
-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}`);
+export async function executeCli(argv, io = process) {
+    const { command, input: rawInput, extraPositionals, flags } = parseArgs(argv);
+    if (command === 'help' || flags.help) {
+        const requestedCommand = command === 'help' ? rawInput : command;
+        const help = buildCliHelp(requestedCommand || null);
+        return help || cliError('UNKNOWN_COMMAND', `Unknown command: ${requestedCommand}`);
+    }
+    if (!command) return cliError('COMMAND_REQUIRED', 'A command is required.');
+    if (!CLI_COMMANDS.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, []);
@@ -336,6 +547,10 @@ export async function executeCli(argv) {
     if (flags.existingRevisions != null && !isExistingRevisionsPolicy(flags.existingRevisions)) {
         return cliError('INVALID_OPERATION', `Unsupported existing-revisions policy: "${String(flags.existingRevisions)}".`);
     }
+    const profile = flags.profile == null ? null : String(flags.profile);
+    if (profile && profile !== 'agent') {
+        return cliError('INVALID_PROFILE', `Unknown execution profile: "${profile}". Supported profiles: agent.`);
+    }
     let inspectOptions = null;
     if (command === 'inspect' || command === 'extract') {
         try { inspectOptions = inspectionOptions(flags); }
@@ -345,11 +560,27 @@ export async function executeCli(argv) {
     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 === 'inspect') {
+            const inspected = document.inspect(inspectOptions);
+            const broadDetailed = !flags.search && flags.index === undefined
+                && flags.indexes === undefined && flags.range === undefined;
+            return boundInspectionResponse(
+                { ...inspected, command, input, indexBase: 1 },
+                { bypass: !!flags.all, broadDetailed }
+            );
+        }
+        if (command === 'extract') {
+            const inspected = document.inspect(inspectOptions);
+            return boundInspectionResponse({
+                status: inspected.status,
+                command,
+                input,
+                indexBase: 1,
+                paragraphs: inspected.paragraphs.map(compactExtractParagraph),
+                ...(inspected.selection ? { selection: inspected.selection } : {}),
+                warnings: inspected.warnings
+            }, { bypass: !!flags.all });
+        }
         if (command === 'validate') {
             const issues = await collectValidationIssues(buffer);
             if (flags.baseline) {
@@ -374,7 +605,9 @@ export async function executeCli(argv) {
             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 opsData = command === 'preflight' || command === 'apply'
+            ? await readOperations(flags.operations, flags, io.stdin || process.stdin)
+            : null;
         const operations = opsData?.operations || null;
         let expectedRevision = opsData?.expectedRevision || null;
         if (flags.expectedRevision) {
@@ -400,15 +633,31 @@ export async function executeCli(argv) {
             }),
             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',
+        };
+        if (command === 'apply') {
+            const agentProfile = profile === 'agent';
+            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 atomic = flags.atomic !== undefined
+                ? (flags.atomic === true || flags.atomic === 'true')
+                : false;
+            const requireComplete = flags.requireComplete !== undefined
+                ? (flags.requireComplete === true || flags.requireComplete === 'true')
+                : agentProfile;
+            const effectiveOptions = {
+                author,
+                atomic,
+                strictTargets: true,
+                validate: true,
+                generateRedlines,
+                existingRevisions: flags.existingRevisions || 'merge-same-author',
+                requireComplete
+            };
+            const result = await document.applyOperations(operations, {
+                author,
+                atomic,
                 validate: true,
                 strictTargets: true,
                 generateRedlines,
@@ -420,7 +669,12 @@ export async function executeCli(argv) {
                 command,
                 input,
                 ...serializable(mutationResult),
-                ...(result.status === 'error' || result.error ? { exitCode: 2 } : {})
+                ...(profile ? { executionProfile: profile, effectiveOptions } : {}),
+                ...(result.status === 'error'
+                    ? { exitCode: 2 }
+                    : (result.status === 'partial' && requireComplete
+                        ? { exitCode: 3 }
+                        : {}))
             });
         }
         const filter = flags.allAuthors ? { allAuthors: true } : flags.author ? { author: String(flags.author) } : null;
@@ -430,8 +684,12 @@ export async function executeCli(argv) {
     } 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;
-}
+export async function runCli(argv = process.argv.slice(2), io = process) {
+    configureLogger({}, { level: 'silent' });
+    const result = await executeCli(argv, io);
+    const compactJson = parseArgs(argv).flags.compact === true;
+    io.stdout.write(`${JSON.stringify(serializable(result), null, compactJson ? 0 : 2)}\n`);
+    return Number.isInteger(result.exitCode) && result.exitCode !== 0
+        ? result.exitCode
+        : (result.status === 'error' ? 1 : 0);
+}