mirror of
https://github.com/morluto/rea.git
synced 2026-11-18 20:53:00 +00:00
Run ordinary CLI commands through REA's registry, argv parser and result owner. Remove Incur, the second admission parse, SDK error middleware, output capture and redundant command traversal. Preserve explicit redaction, publication receipts, incremental output, terminal notice eligibility and drain ownership. Migrate fixtures to real registrations and retain the derived-source notices. Validation includes unchanged public parity goldens, public and lifecycle regressions, repaired fixture consumers, real TTY base comparisons, exports beyond the engine string limit, four schema catalogs and final static/docs checks. Native provider and optional validator coverage limits are in the PR. Fixes #11654. Fixes #10583. Refs #11682, #11476 and #10511. BREAKING CHANGE: Markdown argument diagnostics use REA's literal escaping, table widths and token counts. Flag-shaped unknown MCP subcommands honor the selected format. Completion --schema/--version routes use the canonical REA-owned hook rather than the retired SDK generator. Refresh affected literal snapshots and regenerate completion hooks with rea completions <shell>. Co-authored-by: gensokyo-dev <342580529+gensokyo-dev@users.noreply.github.com>
170 lines
5.9 KiB
TypeScript
170 lines
5.9 KiB
TypeScript
/*
|
||
* The failure envelope, its terminal rendering and the token window of
|
||
* dispatcher-written documents are adapted from Incur's CLI output.
|
||
* Copyright (c) 2025-present weth, LLC
|
||
*
|
||
* Permission is hereby granted, free of charge, to any person obtaining a copy
|
||
* of this software and associated documentation files (the "Software"), to
|
||
* deal in the Software without restriction, including without limitation the
|
||
* rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
|
||
* sell copies of the Software, and to permit persons to whom the Software is
|
||
* furnished to do so, subject to the following conditions:
|
||
*
|
||
* The above copyright notice and this permission notice shall be included in
|
||
* all copies or substantial portions of the Software.
|
||
*
|
||
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
|
||
* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
|
||
* IN THE SOFTWARE.
|
||
*/
|
||
import { estimateTokenCount, sliceByTokens } from "tokenx";
|
||
|
||
import { renderCliDocument, type CliOutputFormat } from "../cliOutput.js";
|
||
import { jsonLinesErrorRecord } from "./jsonLines.js";
|
||
|
||
/** Suggested commands that follow a document. */
|
||
export interface CallToAction {
|
||
readonly description: string;
|
||
readonly commands: readonly {
|
||
readonly command: string;
|
||
readonly description?: string;
|
||
}[];
|
||
}
|
||
|
||
export interface CliFailure {
|
||
readonly code: string;
|
||
readonly message: string;
|
||
}
|
||
|
||
/** How the caller asked for a dispatcher-written document. */
|
||
export interface EnvelopePresentation {
|
||
readonly format: Exclude<CliOutputFormat, "csv" | "tsv">;
|
||
/** A terminal without an explicit format: plain text for a person. */
|
||
readonly human: boolean;
|
||
readonly fullOutput: boolean;
|
||
readonly tokenCount: boolean;
|
||
readonly tokenLimit: number | undefined;
|
||
readonly tokenOffset: number | undefined;
|
||
}
|
||
|
||
/** `Error: message`, or `Error (CODE): message` for codes other than lookup failures. */
|
||
const humanError = ({ code, message }: CliFailure): string =>
|
||
`${code === "UNKNOWN" || code === "COMMAND_NOT_FOUND" ? "Error" : `Error (${code})`}: ${message}`;
|
||
|
||
/** A blank line, the description, then each command with its aligned comment. */
|
||
export const formatCliCallToAction = ({
|
||
description,
|
||
commands,
|
||
}: CallToAction): string => {
|
||
const width = Math.max(...commands.map(({ command }) => command.length));
|
||
return [
|
||
"",
|
||
description,
|
||
...commands.map(
|
||
({ command, description: comment }) =>
|
||
` ${command}${comment === undefined ? "" : ` ${"".padEnd(width - command.length)}# ${comment}`}`,
|
||
),
|
||
].join("\n");
|
||
};
|
||
|
||
/** One line of output: a trailing newline unless the text already ends with one. */
|
||
const line = (text: string): string =>
|
||
text.endsWith("\n") ? text : `${text}\n`;
|
||
|
||
const tokenWindow = (
|
||
text: string,
|
||
{ tokenLimit, tokenOffset }: EnvelopePresentation,
|
||
):
|
||
| { readonly truncated: false; readonly text: string }
|
||
| {
|
||
readonly truncated: true;
|
||
readonly text: string;
|
||
readonly nextOffset: number | undefined;
|
||
} => {
|
||
if (tokenLimit === undefined && tokenOffset === undefined)
|
||
return { truncated: false, text };
|
||
const total = estimateTokenCount(text);
|
||
const offset = tokenOffset ?? 0;
|
||
const end = tokenLimit === undefined ? total : offset + tokenLimit;
|
||
if (offset === 0 && end >= total) return { truncated: false, text };
|
||
const shown = Math.min(end, total);
|
||
return {
|
||
truncated: true,
|
||
text: `${sliceByTokens(text, offset, end)}\n[truncated: showing tokens ${offset}–${shown} of ${total}]`,
|
||
nextOffset: shown < total ? shown : undefined,
|
||
};
|
||
};
|
||
|
||
/**
|
||
* Render a failure the dispatcher reports itself, such as an unknown command.
|
||
* A person on a terminal reads the error and the suggested commands as text;
|
||
* otherwise the error and its suggestions form one document, or the
|
||
* `--full-output` envelope, in the chosen format and token window.
|
||
*/
|
||
export const renderFailure = (
|
||
failure: CliFailure,
|
||
{
|
||
command,
|
||
duration,
|
||
}: { readonly command: string; readonly duration: string },
|
||
cta: CallToAction | undefined,
|
||
presentation: EnvelopePresentation,
|
||
): string => {
|
||
const { format } = presentation;
|
||
const encode = (value: unknown): string =>
|
||
renderCliDocument(value, format, process.stdout.isTTY === true).replace(
|
||
/\n$/u,
|
||
"",
|
||
);
|
||
const meta = { command, ...(cta === undefined ? {} : { cta }), duration };
|
||
const bare = cta === undefined ? failure : { ...failure, cta };
|
||
if (format === "jsonl")
|
||
return renderCliDocument(
|
||
jsonLinesErrorRecord(
|
||
presentation.fullOutput ? { ok: false, error: failure, meta } : bare,
|
||
),
|
||
"jsonl",
|
||
false,
|
||
);
|
||
if (presentation.tokenCount) {
|
||
const document = presentation.fullOutput
|
||
? { ok: false, error: failure, meta }
|
||
: bare;
|
||
return line(String(estimateTokenCount(encode(document))));
|
||
}
|
||
if (
|
||
presentation.human &&
|
||
!presentation.fullOutput &&
|
||
presentation.tokenLimit === undefined &&
|
||
presentation.tokenOffset === undefined
|
||
)
|
||
return (
|
||
line(humanError(failure)) +
|
||
(cta === undefined ? "" : line(formatCliCallToAction(cta)))
|
||
);
|
||
if (presentation.fullOutput) {
|
||
const window = tokenWindow(encode(failure), presentation);
|
||
return line(
|
||
encode(
|
||
window.truncated
|
||
? {
|
||
ok: false,
|
||
error: window.text,
|
||
meta: {
|
||
...meta,
|
||
...(window.nextOffset === undefined
|
||
? {}
|
||
: { nextOffset: window.nextOffset }),
|
||
},
|
||
}
|
||
: { ok: false, error: failure, meta },
|
||
),
|
||
);
|
||
}
|
||
return line(tokenWindow(encode(bare), presentation).text);
|
||
};
|