fix(cli): deliver complete TOON beyond the string limit (#12074)

* fix(cli): deliver complete TOON beyond the string limit

* fix(cli): own cancellation through TOON delivery

* test(cli): await TOON stage acknowledgements

* fix(cli): build TOON cancellations through domain factory

---------

Co-authored-by: ShuaixinHuang <197200901+ShuaixinHuang@users.noreply.github.com>
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
This commit is contained in:
authored and GitHub committed 2026-11-18 20:40:21 -05:00
1 parent bd5c985b3f
commit f10d557f06
10 files changed
+1019 -60

No files matched your search

+83 -26
View File
@@ -38,6 +38,12 @@ import { formatCliCallToAction, type CallToAction } from "./outputEnvelope.js";
import { jsonLinesErrorRecord } from "./jsonLines.js";
import type { OutputFilterPath } from "./outputFilter.js";
import { writeCliJsonLines } from "./jsonLinesOutput.js";
import {
ToonOutputCleanupFailure,
toonOutputCancellationStatus,
writeToonOutput,
} from "./toonOutput.js";
import { analysisErrorWithCleanupDependencies } from "../domain/analysisErrorCleanup.js";
import {
jsonOutputParts,
isTerminalOutput,
@@ -45,6 +51,8 @@ import {
writeOutputParts,
writeOutputText,
} from "./jsonOutput.js";
export { toonOutputCancellationStatus as cliOutputCancellationStatus } from "./toonOutput.js";
/** Result metadata supplied by the command that actually ran. */
export interface CliResultOutputMetadata {
readonly command: string;
@@ -104,6 +112,7 @@ export const createCliResultOutput = (
| "tsv";
let handled = false;
let failed = false;
let interrupted = false;
let error: AnalysisErrorProjection | undefined;
let completed:
| {
@@ -117,38 +126,68 @@ export const createCliResultOutput = (
const recoverFormattingFailure = async (cause: unknown): Promise<boolean> => {
// A rejected command never reaches write(). Destination failures retain
// handled ownership. Only a completed, unwritten result can be replaced.
const formattingCause =
cause instanceof ToonOutputCleanupFailure
? cause.outputFailure?.cause
: cause;
if (
completed === undefined ||
handled ||
hostRangeErrorKind(cause) !== "host-capacity" ||
!(cause instanceof Error) ||
cause.message !== "Invalid string length"
!(formattingCause instanceof Error)
)
return false;
const stringCapacity =
hostRangeErrorKind(formattingCause) === "host-capacity" &&
formattingCause.message === "Invalid string length";
const systemCode =
"code" in formattingCause ? formattingCause.code : undefined;
const stagingCapacity =
format === "toon" &&
(systemCode === "ENOSPC" ||
systemCode === "EDQUOT" ||
systemCode === "EFBIG")
? systemCode
: undefined;
if (!stringCapacity && stagingCapacity === undefined) return false;
const { originalFailure } = completed;
error = projectAnalysisError(
retainCliPublicationOnError(
new AnalysisResourceConstraintError(
completed.metadata.command,
"memory",
`The ${format} result could not fit in a runtime string. The original result was not written.`,
{
format,
formatted_characters: null,
max_string_characters: constants.MAX_STRING_LENGTH,
...(originalFailure === undefined
? {}
: { original_failure: originalFailure }),
},
{
cause,
retryable: false,
remediationAction:
"Use --format json to stream the complete result, or narrow it with --filter-output. Token limits are applied after formatting and cannot avoid this constraint.",
},
),
completed.receipt,
const refusal = retainCliPublicationOnError(
new AnalysisResourceConstraintError(
completed.metadata.command,
stagingCapacity === undefined ? "memory" : "capacity",
stagingCapacity === undefined
? `The ${format} result could not fit in a runtime string. The original result was not written.`
: "The temporary storage could not stage the TOON result. The original result was not written.",
{
format,
...(stagingCapacity === undefined
? {
formatted_characters: null,
max_string_characters: constants.MAX_STRING_LENGTH,
}
: { system_code: stagingCapacity }),
...(originalFailure === undefined
? {}
: { original_failure: originalFailure }),
},
{
cause: formattingCause,
retryable: false,
remediationAction:
stagingCapacity === undefined
? "Use --format json to stream the complete result, or narrow it with --filter-output. Token limits are applied after formatting and cannot avoid this constraint."
: "Free space in the system temporary directory, use --format json, or narrow the result with --filter-output.",
},
),
completed.receipt,
);
error = projectAnalysisError(
cause instanceof ToonOutputCleanupFailure
? analysisErrorWithCleanupDependencies(
refusal,
cause,
completed.metadata.command,
)
: refusal,
);
const document = options.fullOutput
? {
@@ -231,6 +270,12 @@ export const createCliResultOutput = (
}
return written;
} catch (cause: unknown) {
if (toonOutputCancellationStatus(cause) !== undefined) {
interrupted = true;
handled = true;
failed = true;
throw cause;
}
if (await recoverFormattingFailure(cause)) return true;
if (handled) failed = true;
throw cause;
@@ -251,11 +296,12 @@ export const createCliResultOutput = (
format = options.format as typeof format;
handled = false;
failed = false;
interrupted = false;
error = undefined;
completed = undefined;
},
finish() {
return writeOutputText(destination, "");
return interrupted ? Promise.resolve() : writeOutputText(destination, "");
},
write,
recoverFormattingFailure,
@@ -640,6 +686,17 @@ export const createCliResultOutput = (
}
return true;
}
if (format === "toon") {
await writeToonOutput(
document,
destination,
() => {
handled = true;
},
metadata.command,
);
return true;
}
// Once writing starts, a failed destination must not receive another document.
const formattedText =
format === "json" ? undefined : formatCliOutput(document, format);
+48 -16
View File
@@ -7,28 +7,60 @@ export interface CommandCancellationHost {
exitCode?: number | string | null | undefined;
}
/** Own process signals until both the operation and its resources settle. */
export class CommandCancellationScope {
readonly #controller = new AbortController();
#exitStatus: 130 | 143 | undefined;
#finished = false;
#closed = false;
constructor(private readonly host: CommandCancellationHost = process) {
host.on("SIGINT", this.#interrupt);
host.on("SIGTERM", this.#terminate);
}
get signal(): AbortSignal {
return this.#controller.signal;
}
get exitStatus(): 130 | 143 | undefined {
return this.#exitStatus;
}
readonly #interrupt = () => this.#abort("SIGINT", 130);
readonly #terminate = () => this.#abort("SIGTERM", 143);
#abort(signal: "SIGINT" | "SIGTERM", status: 130 | 143): void {
this.#exitStatus ??= status;
this.#controller.abort(CallerAbort.forProcessSignal(signal));
if (this.#finished) this.finish();
}
/** Publish the disposition while a failed resource close still owns signals. */
finish(): void {
this.#finished = true;
if (this.#exitStatus !== undefined) this.host.exitCode = this.#exitStatus;
}
/** Release signal ownership only after the resource owner confirms cleanup. */
close(): void {
if (this.#closed) return;
this.#closed = true;
this.host.off("SIGINT", this.#interrupt);
this.host.off("SIGTERM", this.#terminate);
this.finish();
}
}
/** Translate one-shot CLI interrupts into awaited cleanup and conventional exit codes. */
export const withCommandCancellation = async <Value>(
operation: (signal: AbortSignal) => Promise<Value>,
host: CommandCancellationHost = process,
): Promise<Value> => {
const controller = new AbortController();
let exitCode: number | undefined;
const interrupt = () => {
exitCode ??= 130;
controller.abort(CallerAbort.forProcessSignal("SIGINT"));
};
const terminate = () => {
exitCode ??= 143;
controller.abort(CallerAbort.forProcessSignal("SIGTERM"));
};
host.on("SIGINT", interrupt);
host.on("SIGTERM", terminate);
const scope = new CommandCancellationScope(host);
try {
return await operation(controller.signal);
return await operation(scope.signal);
} finally {
host.off("SIGINT", interrupt);
host.off("SIGTERM", terminate);
if (exitCode !== undefined) host.exitCode = exitCode;
scope.close();
}
};
+227
View File
@@ -0,0 +1,227 @@
import { open } from "node:fs/promises";
import { join } from "node:path";
import type { Writable } from "node:stream";
import { encodeLines } from "@toon-format/toon";
import {
AnalysisCancelledError,
cancelledBy,
} from "../domain/analysisErrorCore.js";
import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
import { CommandCancellationScope } from "./commandCancellation.js";
import { bufferedJsonParts } from "../domain/jsonSerialization.js";
import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
import { ProviderCleanupError } from "../domain/providerCleanupError.js";
import {
AnalysisCleanupLease,
AnalysisCleanupLeaseGroup,
ArtifactResourceScope,
} from "../resources/index.js";
import { ownCliProcessResource } from "./cliResources.js";
import { formatCliOutput } from "./cliOutputFormatter.js";
import { writeOutputParts, writeOutputText } from "./jsonOutput.js";
const retainedStages = new Set<ArtifactResourceScope>();
ownCliProcessResource("toon-output", async () => {
const failures: unknown[] = [];
for (const resources of retainedStages) {
try {
await resources.close();
retainedStages.delete(resources);
} catch (cause: unknown) {
failures.push(cause);
}
}
if (failures.length === 1) throw failures[0];
if (failures.length > 1)
throw new AggregateError(failures, "TOON staging cleanup failed");
});
/** The stage owns both its original output failure and retryable cleanup. */
export class ToonOutputCleanupFailure extends ProviderCleanupError {
constructor(
readonly outputFailure: { readonly cause: unknown } | undefined,
operation: string,
resources: readonly string[],
cleanupCause: unknown,
) {
super(
"cli-toon-output",
resources,
{
reason:
cleanupCause instanceof Error
? cleanupCause.message
: "Stage cleanup failed",
},
{
operation,
cause: new AggregateError(
[
...(outputFailure === undefined ? [] : [outputFailure.cause]),
cleanupCause,
],
"TOON output and cleanup failures",
),
},
);
}
}
// Only this output owner can attest a process disposition for a cancellation.
// The shared factory remains the sole constructor of the domain error.
const cancellationStatuses = new WeakMap<AnalysisCancelledError, 130 | 143>();
/** Read the output owner's disposition without inferring it from ambient state. */
export const toonOutputCancellationStatus = (
cause: unknown,
): 130 | 143 | undefined => {
const failure =
cause instanceof ToonOutputCleanupFailure
? cause.outputFailure?.cause
: cause;
return failure instanceof AnalysisCancelledError
? cancellationStatuses.get(failure)
: undefined;
};
function* toonParts(value: object): Generator<string> {
for (const line of encodeLines(value)) {
yield line;
yield "\n";
}
}
/**
* Complete encoding before releasing stdout. Keep a small document in memory
* and stage a larger one privately so a late encoding failure publishes no
* prefix. The same encoded bytes are read back without visiting the input again.
*/
export const writeToonOutput = async (
value: unknown,
destination: Writable,
beginOutput: () => void,
operation: string,
): Promise<void> => {
if (typeof value !== "object" || value === null) {
const text = `${formatCliOutput(value, "toon")}\n`;
beginOutput();
await writeOutputText(destination, text);
return;
}
const parts = bufferedJsonParts(toonParts(value));
try {
const buffered: string[] = [];
let characters = 0;
let next = parts.next();
while (!next.done && characters + next.value.length <= 1024 * 1024) {
buffered.push(next.value);
characters += next.value.length;
next = parts.next();
}
if (next.done) {
beginOutput();
await writeOutputParts(
destination,
buffered.length === 0 ? ["\n"] : buffered,
);
return;
}
const firstStagedPart = next.value;
const cancellation = new CommandCancellationScope();
let retained = false;
const cancelled = () => {
const status = cancellation.exitStatus;
if (status === undefined) return undefined;
const failure = cancelledBy(operation, cancellation.signal);
cancellationStatuses.set(failure, status);
return failure;
};
const checkCancellation = () => {
const failure = cancelled();
if (failure !== undefined) throw failure;
};
try {
const root = await PrivateRuntimeRoot.create({ prefix: "rea-toon-" });
const directory = root.path;
const path = join(directory, "output");
const resources = new ArtifactResourceScope();
let owner: OwnedFileHandle | undefined;
const lease = new AnalysisCleanupLease(
async () => {
await owner?.close();
owner = undefined;
await root.close();
cancellation.close();
},
{
get cleanupResources() {
return owner === undefined ? [directory] : [path, directory];
},
},
);
let failure: { cause: unknown } | undefined;
try {
checkCancellation();
owner = new OwnedFileHandle(await open(path, "wx+", 0o600));
const file = owner.handle;
const stage = async (part: string) => {
checkCancellation();
await file.writeFile(part);
checkCancellation();
};
for (const part of buffered) await stage(part);
await stage(firstStagedPart);
for (const part of parts) await stage(part);
checkCancellation();
beginOutput();
// Early iterator return must not invalidate the descriptor behind its
// owner. The lease closes the handle after pending reads settle.
const chunks: AsyncIterable<string> = file
.createReadStream({
start: 0,
autoClose: false,
encoding: "utf8",
})
.iterator({ destroyOnReturn: false });
for await (const chunk of chunks) {
checkCancellation();
await writeOutputText(destination, chunk);
checkCancellation();
}
} catch (cause: unknown) {
failure = { cause };
}
const cleanup = await resources.release({
kind: "lease",
resource: directory,
lease,
});
// An interrupt during the last close/removal is still this operation's.
const lateCancellation = cancelled();
if (failure === undefined && lateCancellation !== undefined)
failure = { cause: lateCancellation };
if (cleanup.kind === "failed") {
retainedStages.add(resources);
retained = true;
const error = new ToonOutputCleanupFailure(
failure,
operation,
lease.cleanupResources ?? [directory],
cleanup.cause,
);
new AnalysisCleanupLeaseGroup(error, [lease]);
throw error;
}
if (failure !== undefined) throw failure.cause;
} finally {
cancellation.finish();
if (!retained) cancellation.close();
}
} finally {
parts.return(undefined);
}
};