From a10037ef10516cf92653596512932b15f190a5c0 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Mon, 16 Nov 2026 14:46:48 +0800 Subject: [PATCH] refactor(cli): report unknown commands and the update notice from REA (#11692) * refactor(cli): render help pages with REA's help owner REA now renders the root page, every command page, help after an unknown command, the mcp group page, the mcp doctor builtin page and the completions page before incur sees argv, with incur's precedence (update check, --update without help, --mcp and the LLM manifests first; then the integrations; then --version; then root and command pages). help.ts gains arguments, custom global options, the root-only flags and integrations, and a command-list page. The --format row on the root and command pages now lists csv and tsv (#10250), the approved difference; the mcp and mcp add pages keep the document formats they accept. Every other help byte is unchanged: 397 pages compared with incur's Help for all 196 registered commands. Fixes #10250 * test(cli): elide the root command list wherever the root page is printed The golden renderer chose root-page elision by case name, so help after an unknown command froze the whole command list. It now elides any stdout that opens with the root page's rea@ title. * refactor(cli): answer --version, --schema and the LLM manifests in REA src/cli/discovery.ts answers help, --version, --schema, --llms and --llms-full with incur's precedence, reading the arguments as the dispatcher receives them (after result output has adapted them, so token counts and buffering are unchanged). commandManifests.ts renders the Markdown index and full manifest, the structured manifests and the --schema document; commandSuggestion.ts ranks Did-you-mean candidates. Both are adapted from incur under its MIT licence. --schema --format md stays with incur: incur renders it without Markdown escaping, unlike REA's renderer, and that difference awaits a decision on #11654. Compared with incur's serve for every registered command and format, 3746 of 3945 discovery invocations are identical; the rest are the 196 Markdown schemas left to incur and the three root help pages with the approved csv/tsv row. * test(cli): pin which discovery document wins when several are asked for Goldens for --llms with --help, --llms with --version, --llms with --llms-full, --schema with --version and --schema with --help, recorded with incur's rendering on the base branch. * refactor(cli): report unknown commands and the update notice from REA src/cli/updateNotice.ts owns the terminal update notice: the same trigger (terminal stdout, no explicit format), text, cache file ($XDG_CACHE_HOME/incur/updates/.json), daily detached refresh through rea --incur-update-check, and opt-outs (NO_UPDATE_NOTIFIER, npm_config_update_notifier=false, CI). Discovery answers the detached refresh first, and reports an unknown command with incur's Did-you-mean suggestion, corrected invocation, help command and notice, as text on a terminal or as the error document, full-output envelope, token count or token window otherwise. outputEnvelope.ts renders these dispatcher failures. Unknown commands with --format md stay with incur pending the Markdown escaping decision on #11654. Compared with incur's serve, 224 of 224 unknown-command invocations are identical, piped and on a terminal with a due notice. * fix(cli): redact unknown-command guidance before rendering Share the producing reply boundary for root lookup, unknown schemas and MCP subcommands. Preserve ordinary argument identity and existing MCP suggestion policies; omit sensitive or unsafe replay commands and redact full-output command metadata. Co-authored-by: gensokyo-dev <342580529+gensokyo-dev@users.noreply.github.com> --------- Co-authored-by: gensokyo-dev Co-authored-by: gensokyo-dev <342580529+gensokyo-dev@users.noreply.github.com> --- src/cli/cliShell.ts | 9 +- src/cli/discovery.ts | 133 +++++-- src/cli/mcpBuiltinCommands.ts | 100 +++-- src/cli/outputEnvelope.ts | 144 +++++++ src/cli/unknownCommandReply.ts | 72 ++++ src/cli/updateNotice.ts | 350 ++++++++++++++++++ tests/boundary/cli/cliParityGoldens.test.ts | 8 + .../cli/unknownCommandSensitivity.test.ts | 138 +++++++ tests/boundary/cli/updateCheckRefresh.test.ts | 80 ++++ .../error-unknown-command-full-output.txt | 7 + .../error-unknown-command-token-limit.txt | 8 + .../updateNoticeEnvironment.test.ts | 94 +++++ 12 files changed, 1065 insertions(+), 78 deletions(-) create mode 100644 src/cli/outputEnvelope.ts create mode 100644 src/cli/unknownCommandReply.ts create mode 100644 src/cli/updateNotice.ts create mode 100644 tests/boundary/cli/unknownCommandSensitivity.test.ts create mode 100644 tests/boundary/cli/updateCheckRefresh.test.ts create mode 100644 tests/fixtures/cli-parity/error-unknown-command-full-output.txt create mode 100644 tests/fixtures/cli-parity/error-unknown-command-token-limit.txt create mode 100644 tests/process-global/updateNoticeEnvironment.test.ts diff --git a/src/cli/cliShell.ts b/src/cli/cliShell.ts index 5d67bc785a..cdb86e2629 100644 --- a/src/cli/cliShell.ts +++ b/src/cli/cliShell.ts @@ -148,10 +148,13 @@ export const createCliShell = (options: CliShellOptions): CliInstance => { // Discovery reads the arguments the dispatcher would, after result output // has adapted them, so its documents are counted and buffered alike. const dispatch = cli.serve.bind(cli); + const updateEnvironment = { + variables: environment, + platform: HOST_PLATFORM.platform, + }; cli.serve = (arguments_ = process.argv.slice(2), serveOptions) => - serveDiscovery(cli, arguments_, serveOptions ?? {}) - ? Promise.resolve() - : dispatch(arguments_, serveOptions); + serveDiscovery(cli, arguments_, serveOptions ?? {}, updateEnvironment) ?? + dispatch(arguments_, serveOptions); if (options.resultOutput !== undefined) streamCliCommandResults(cli, options.resultOutput); const serveStrict = validateCliArguments(cli); diff --git a/src/cli/discovery.ts b/src/cli/discovery.ts index a73e00a46a..aec0cf909c 100644 --- a/src/cli/discovery.ts +++ b/src/cli/discovery.ts @@ -20,6 +20,15 @@ import { } from "./commandManifests.js"; import { cliCommands, type CliCommandEntry } from "./commandRegistry.js"; import { suggestCommand } from "./commandSuggestion.js"; +import { unknownCommandReply } from "./unknownCommandReply.js"; +import { renderFailure } from "./outputEnvelope.js"; +import { + availableUpdate, + refreshUpdateCache, + UPDATE_CHECK_FLAG, + updateNoticeCta, + type UpdateEnvironment, +} from "./updateNotice.js"; import { formatCommandHelp, formatCommandListHelp, @@ -156,9 +165,8 @@ const llmsAnswer = ( }; /** - * `--schema` for a command, or the error for an unknown one. Markdown stays - * with the dispatcher: it renders the document without Markdown escaping, - * unlike REA's renderer, and that difference awaits a decision (#11654). + * `--schema` for a command, or the error for an unknown one. Known-command + * Markdown stays with the dispatcher until the remaining execution migration. */ const schemaAnswer = ( cli: CliInstance, @@ -171,10 +179,13 @@ const schemaAnswer = ( name, cliCommands(cli).map((command) => command.name), ); - return answer( - `Error: '${name}' is not a command for '${cli.name}'.${suggestion === undefined ? "" : ` Did you mean '${suggestion}'?`}`, - 1, - ); + const { failure } = unknownCommandReply({ + name: cli.name, + global, + commandIndex: 0, + suggestion, + }); + return answer(`Error: ${failure.message}`, 1); } const { format, formatExplicit } = readCliOutputArguments(global); if (formatExplicit && format === "md") return undefined; @@ -186,27 +197,86 @@ const schemaAnswer = ( ); }; +/** Facts about one invocation's process that discovery output depends on. */ +interface Invocation { + readonly environment: UpdateEnvironment; + readonly stdoutIsTerminal: boolean; + /** `performance.now()` when the dispatcher received the invocation. */ + readonly started: number; +} + +/** + * An unknown command: the closest command name, the corrected invocation and + * the help command. On a terminal without an explicit format the error is + * text, followed by the update notice when one is due. + */ +const unknownCommandAnswer = ( + cli: CliInstance, + global: CliGlobalArguments, + { environment, stdoutIsTerminal, started }: Invocation, +): DiscoveryAnswer | undefined => { + const controls = readCliOutputArguments(global); + const format = controls.formatExplicit ? controls.format : "toon"; + if (format === "csv" || format === "tsv") return undefined; + const human = stdoutIsTerminal && !controls.formatExplicit; + const unknown = global.command[0]!; + const suggestion = suggestCommand(unknown, [ + ...cliCommands(cli).map(({ name }) => name), + "completions", + "mcp", + ]); + const update = human + ? availableUpdate(cli.name, PRODUCT_IDENTITY.packageVersion, environment) + : undefined; + const notice = + update === undefined ? [] : updateNoticeCta(cli.name, update).commands; + const { command, cta, failure } = unknownCommandReply({ + name: cli.name, + global, + commandIndex: 0, + suggestion, + additionalCommands: notice, + }); + return answer( + renderFailure( + failure, + { + command, + duration: `${Math.round(performance.now() - started)}ms`, + }, + cta, + { + format, + human, + fullOutput: controls.fullOutput, + tokenCount: controls.tokenCount, + tokenLimit: controls.tokenLimit, + tokenOffset: controls.tokenOffset, + }, + ), + 1, + ); +}; + /** * The document an invocation asks for instead of running a command, or - * undefined. Precedence: the update check, `--update` without help and - * `--mcp` stay with the dispatcher; the LLM manifests answer next; then the + * undefined. Precedence (after the detached update refresh): `--update` + * without help and `--mcp` stay with the dispatcher; the LLM manifests answer + * next; then the * integrations (`completions` shows its page for help or without a shell, * `mcp` shows its page without a subcommand); then `--version` without help; * then the root page for no command; then a command's page for help (help - * after an unknown command shows the root page); then `--schema`. + * after an unknown command shows the root page); then `--schema`; then the + * unknown-command error. */ const discoveryAnswer = ( cli: CliInstance, global: CliGlobalArguments, + invocation: Invocation, ): DiscoveryAnswer | undefined => { const { command, flags } = global; const help = flags.has("--help") || flags.has("-h"); - if ( - flags.has("--incur-update-check") || - (flags.has("--update") && !help) || - flags.has("--mcp") - ) - return undefined; + if ((flags.has("--update") && !help) || flags.has("--mcp")) return undefined; if (flags.has("--llms") || flags.has("--llms-full")) return llmsAnswer(cli, global, flags.has("--llms-full")); const completions = integrationIndex(command, cli.name, "completions"); @@ -265,27 +335,42 @@ const discoveryAnswer = ( ); } if (flags.has("--schema")) return schemaAnswer(cli, global); - return undefined; + if (cliCommands(cli).some(({ name }) => name === command[0])) + return undefined; + return unknownCommandAnswer(cli, global, invocation); }; type ServeOptions = NonNullable[1]>; /** - * Answer help, `--version`, `--schema` and the LLM manifests, reading the - * arguments as the command dispatcher receives them. Returns false when the - * invocation asks for something else. + * Answer the detached update refresh, help, `--version`, `--schema`, the + * LLM manifests and unknown commands, reading the arguments as the command dispatcher receives + * them. Returns undefined when the invocation asks for something else. */ export const serveDiscovery = ( cli: CliInstance, arguments_: readonly string[], options: ServeOptions, -): boolean => { - const result = discoveryAnswer(cli, parseCliGlobalArguments(arguments_)); - if (result === undefined) return false; + environment: UpdateEnvironment, +): Promise | undefined => { + const global = parseCliGlobalArguments(arguments_); + // The refresh writes nothing and answers before every other flag. + if (global.flags.has(UPDATE_CHECK_FLAG)) + return refreshUpdateCache( + cli.name, + PRODUCT_IDENTITY.packageVersion, + environment, + ); + const result = discoveryAnswer(cli, global, { + environment, + stdoutIsTerminal: process.stdout.isTTY === true, + started: performance.now(), + }); + if (result === undefined) return undefined; (options.stdout ?? ((text: string) => process.stdout.write(text)))( result.text, ); if (result.exitCode !== 0) (options.exit ?? ((code: number) => process.exit(code)))(result.exitCode); - return true; + return Promise.resolve(); }; diff --git a/src/cli/mcpBuiltinCommands.ts b/src/cli/mcpBuiltinCommands.ts index 7557f13100..3640141b4b 100644 --- a/src/cli/mcpBuiltinCommands.ts +++ b/src/cli/mcpBuiltinCommands.ts @@ -2,7 +2,6 @@ import { mcpRegistrationOptionsSchema } from "../contracts/mcpRegistration.js"; import { adaptCliOutputArgumentsForIncur, - declaredSensitiveValues, parseCliGlobalArguments, type CliGlobalArguments, } from "../cliBuiltinArguments.js"; @@ -11,7 +10,9 @@ import { renderCliDocument, type CliOutputFormat, } from "../cliOutput.js"; -import { redactExplicitText } from "../domain/explicitSensitiveValues.js"; +import { renderFailure } from "./outputEnvelope.js"; +import { suggestCommand } from "./commandSuggestion.js"; +import { unknownCommandReply } from "./unknownCommandReply.js"; import type { CliInstance } from "./types.js"; type ServeOptions = NonNullable[1]>; @@ -38,13 +39,11 @@ const PRECEDING_BUILTIN_FLAGS: ReadonlySet = new Set([ "--mcp", ]); -// zsh expands a word that starts with `=` to an executable path. -const PLAIN_SHELL_WORD = /^(?!=)[\w./+=:,-]+$/u; - /** * Incur 0.6.1 rejects an unknown `mcp` subcommand in TOON regardless of the - * selected format. Report the same envelope in the explicitly selected format; - * without one, Incur's TOON or human rendering is already the selected output. + * selected format. Report the same document in the explicitly selected format, + * or preserve the default TOON/human presentation. Both paths honor explicit + * sensitive-value declarations before rendering. * The caller's arguments are read before REA adapts output flags for Incur, * so the suggested command keeps the caller's selection. */ @@ -53,7 +52,8 @@ export const reportUnknownMcpSubcommand = ( global: CliGlobalArguments, options: ServeOptions, ): boolean => { - const { arguments: arguments_, command, commandIndices } = global; + const started = performance.now(); + const { arguments: arguments_, command } = global; const [entry, subcommand] = command; // Incur receives JSON for REA's delimited formats and no `--columns`. const incur = parseCliGlobalArguments( @@ -79,51 +79,49 @@ export const reportUnknownMcpSubcommand = ( return false; const output = readCliOutputArguments(incur); // Invalid output controls keep Incur's own parse diagnostic. - if (!output.formatExplicit || !output.validation.ok) return false; - const sensitive = declaredSensitiveValues(command); - const text = (value: string): string => redactExplicitText(value, sensitive); - const suggestion = [...MCP_SUBCOMMANDS.keys()].find((candidate) => - candidate.startsWith(subcommand.toLowerCase()), - ); - const corrected = arguments_.map((token, index) => - index === commandIndices[1] ? suggestion : token, - ); - // Joined tokens replay only when each one is a plain word in every shell; - // quoting is shell-specific, and a redacted value cannot be replayed. - const replayable = - suggestion !== undefined && - corrected.every( - (token) => - token !== undefined && - PLAIN_SHELL_WORD.test(token) && - text(token) === token, - ); - const commands = [ - ...(replayable ? [{ command: `${name} ${corrected.join(" ")}` }] : []), - { - command: text(`${name} mcp --help`), - description: text("see all available commands"), - }, - ]; - const document = { - code: "COMMAND_NOT_FOUND", - message: text( - `'${subcommand}' is not a command for '${name} mcp'.${suggestion === undefined ? "" : ` Did you mean '${suggestion}'?`}`, - ), - cta: { - description: text( - commands.length === 1 ? "Suggested command:" : "Suggested commands:", - ), - commands, - }, - }; + if (!output.validation.ok) return false; + // Preserve the existing explicit-format prefix policy and the default + // dispatcher's edit-distance ranking while moving both replies to one owner. + const suggestion = output.formatExplicit + ? [...MCP_SUBCOMMANDS.keys()].find((candidate) => + candidate.startsWith(subcommand.toLowerCase()), + ) + : suggestCommand(subcommand, MCP_SUBCOMMANDS.keys()); + const { + command: displayCommand, + cta, + failure, + } = unknownCommandReply({ + name, + scope: ["mcp"], + global, + commandIndex: 1, + suggestion, + }); (options.stdout ?? ((value: string) => process.stdout.write(value)))( // REA's document renderer owns JSON layout and Markdown escaping. - renderCliDocument( - document, - output.format as CliOutputFormat, - process.stdout.isTTY === true, - ), + output.formatExplicit + ? renderCliDocument( + { ...failure, cta }, + output.format as CliOutputFormat, + process.stdout.isTTY === true, + ) + : renderFailure( + failure, + { + command: displayCommand, + duration: `${Math.round(performance.now() - started)}ms`, + }, + cta, + { + format: "toon", + human: process.stdout.isTTY === true, + fullOutput: false, + tokenCount: false, + tokenLimit: undefined, + tokenOffset: undefined, + }, + ), ); (options.exit ?? ((code: number) => process.exit(code)))(1); return true; diff --git a/src/cli/outputEnvelope.ts b/src/cli/outputEnvelope.ts new file mode 100644 index 0000000000..6c0defd6d7 --- /dev/null +++ b/src/cli/outputEnvelope.ts @@ -0,0 +1,144 @@ +/* + * 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 type { CliOutputFormat } from "../cliOutput.js"; +import { formatCliOutput } from "./cliOutputFormatter.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; + /** 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. */ +const humanCallToAction = ({ 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, + presentation: EnvelopePresentation, +): string => { + if (presentation.human && !presentation.fullOutput) + return line(humanError(failure)) + line(humanCallToAction(cta)); + const { format } = presentation; + if (presentation.tokenCount) + return line(String(estimateTokenCount(formatCliOutput(failure, format)))); + const meta = { command, cta, duration }; + if (presentation.fullOutput) { + const window = tokenWindow(formatCliOutput(failure, format), presentation); + return line( + formatCliOutput( + window.truncated + ? { + ok: false, + error: window.text, + meta: { + ...meta, + ...(window.nextOffset === undefined + ? {} + : { nextOffset: window.nextOffset }), + }, + } + : { ok: false, error: failure, meta }, + format, + ), + ); + } + return line( + tokenWindow(formatCliOutput({ ...failure, cta }, format), presentation) + .text, + ); +}; diff --git a/src/cli/unknownCommandReply.ts b/src/cli/unknownCommandReply.ts new file mode 100644 index 0000000000..b8eb9d0e5b --- /dev/null +++ b/src/cli/unknownCommandReply.ts @@ -0,0 +1,72 @@ +import { + declaredSensitiveValues, + type CliGlobalArguments, +} from "../cliBuiltinArguments.js"; +import { redactExplicitText } from "../domain/explicitSensitiveValues.js"; +import type { CallToAction } from "./outputEnvelope.js"; + +// Joined tokens replay only as plain words in every supported shell. Quoting +// is shell-specific, and a redacted command cannot be replayed faithfully. +const PLAIN_SHELL_WORD = /^(?!=)[\w./+=:,-]+$/u; + +/** One owner for unknown-command text and safe, declaration-aware guidance. */ +export const unknownCommandReply = ({ + name, + scope = [], + global, + commandIndex, + suggestion, + additionalCommands = [], +}: { + readonly name: string; + readonly scope?: readonly string[]; + readonly global: CliGlobalArguments; + readonly commandIndex: number; + readonly suggestion: string | undefined; + readonly additionalCommands?: CallToAction["commands"]; +}) => { + const sensitive = declaredSensitiveValues(global.command); + const text = (value: string): string => redactExplicitText(value, sensitive); + const parent = [name, ...scope].join(" "); + const unknown = global.command[commandIndex]!; + const corrected = [ + name, + ...global.arguments.map((token, index) => + index === global.commandIndices[commandIndex] ? suggestion : token, + ), + ]; + const replayable = + suggestion !== undefined && + corrected.every( + (token) => + token !== undefined && + PLAIN_SHELL_WORD.test(token) && + text(token) === token, + ); + const commands = [ + ...(replayable ? [{ command: corrected.join(" ") }] : []), + { command: `${parent} --help`, description: "see all available commands" }, + ]; + return { + command: text(unknown), + failure: { + code: "COMMAND_NOT_FOUND", + message: text( + `'${unknown}' is not a command for '${parent}'.${suggestion === undefined ? "" : ` Did you mean '${suggestion}'?`}`, + ), + }, + cta: { + description: text( + commands.length === 1 ? "Suggested command:" : "Suggested commands:", + ), + commands: [...commands, ...additionalCommands].map( + ({ command, description }) => ({ + command: text(command), + ...(description === undefined + ? {} + : { description: text(description) }), + }), + ), + }, + }; +}; diff --git a/src/cli/updateNotice.ts b/src/cli/updateNotice.ts new file mode 100644 index 0000000000..ba9855f2f4 --- /dev/null +++ b/src/cli/updateNotice.ts @@ -0,0 +1,350 @@ +/* + * The update notice, its cache and its detached refresh are adapted from + * Incur's update checks. + * 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 { spawn } from "node:child_process"; +import { mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs"; +import { userInfo } from "node:os"; +import { dirname, join } from "node:path"; + +/** + * The terminal update notice. On a terminal without an explicit format, a + * command's output (and an unknown-command error) ends with "Update available" + * when the cached latest version is newer than the running one. A cache older + * than a day is marked checked and refreshed by a detached `rea + * --incur-update-check`, which asks the npm registry for the latest version. + * `NO_UPDATE_NOTIFIER`, `npm_config_update_notifier=false` and `CI` turn the + * notice and the refresh off. The cache lives at + * `$XDG_CACHE_HOME/incur/updates/.json`, where earlier releases kept + * it. + */ + +/** The hidden flag of the detached refresh. */ +export const UPDATE_CHECK_FLAG = "--incur-update-check"; + +const REFRESH_INTERVAL_MS = 24 * 60 * 60 * 1_000; +const REGISTRY_TIMEOUT_MS = 10_000; + +/** + * The selected CLI snapshot and the platform that gave its keys identity. + * Both notice decisions and the refresh child consume this same snapshot. + */ +export interface UpdateEnvironment { + readonly variables: Readonly>; + readonly platform: NodeJS.Platform; +} + +const variable = (environment: UpdateEnvironment, name: string) => + environment.variables[ + environment.platform === "win32" ? name.toUpperCase() : name + ]; + +export interface AvailableUpdate { + readonly name: string; + readonly current: string; + readonly latest: string; +} + +interface UpdateCache { + readonly checkedAt: number; + readonly latest?: string; +} + +interface Version { + readonly core: readonly [bigint, bigint, bigint]; + readonly prerelease: readonly (bigint | string)[]; +} + +const SEMVER = + /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/u; + +const parseVersion = (version: string): Version | undefined => { + const match = SEMVER.exec(version); + if (match === null) return undefined; + const prerelease: (bigint | string)[] = []; + for (const identifier of match[4]?.split(".") ?? []) { + if (!/^\d+$/u.test(identifier)) prerelease.push(identifier); + else if (identifier.length > 1 && identifier.startsWith("0")) + return undefined; + else prerelease.push(BigInt(identifier)); + } + return { + core: [BigInt(match[1]!), BigInt(match[2]!), BigInt(match[3]!)], + prerelease, + }; +}; + +/** Whether `candidate` has higher semantic-version precedence than `current`. */ +export const isNewerVersion = (candidate: string, current: string): boolean => { + const next = parseVersion(candidate); + const now = parseVersion(current); + if (next === undefined || now === undefined) return false; + for (let index = 0; index < 3; index += 1) { + if (next.core[index]! > now.core[index]!) return true; + if (next.core[index]! < now.core[index]!) return false; + } + if (next.prerelease.length === 0) return now.prerelease.length > 0; + if (now.prerelease.length === 0) return false; + const length = Math.max(next.prerelease.length, now.prerelease.length); + for (let index = 0; index < length; index += 1) { + const left = next.prerelease[index]; + const right = now.prerelease[index]; + if (left === undefined) return false; + if (right === undefined) return true; + if (left === right) continue; + if (typeof left === "bigint" && typeof right === "string") return false; + if (typeof left === "string" && typeof right === "bigint") return true; + return left > right; + } + return false; +}; + +const notificationsDisabled = (environment: UpdateEnvironment): boolean => { + const ci = variable(environment, "CI"); + return ( + Boolean(variable(environment, "NO_UPDATE_NOTIFIER")) || + variable(environment, "npm_config_update_notifier") === "false" || + Boolean(ci && ci !== "false") + ); +}; + +const isPackageName = (name: string): boolean => + /^(?:@[A-Za-z0-9][A-Za-z0-9._~-]*\/)?[A-Za-z0-9][A-Za-z0-9._~-]*$/u.test( + name, + ); + +/** Whether package metadata declares the CLI. */ +const providesCli = (metadata: Record, cli: string) => { + if (metadata.name === cli) return true; + const { bin, name } = metadata; + if (typeof bin === "object" && bin !== null && cli in bin) return true; + return ( + typeof bin === "string" && + typeof name === "string" && + name.split("/").pop() === cli + ); +}; + +/** + * The npm package of the running entry script, found by walking up from it. + * Only an installed or checked-out package that provides the CLI qualifies. + */ +const runningPackage = ( + cli: string, +): { readonly name: string; readonly version: string } | undefined => { + const script = process.argv[1]; + if (!script) return undefined; + let directory: string; + try { + directory = dirname(realpathSync(script)); + } catch { + return undefined; + } + for (;;) { + try { + const metadata = JSON.parse( + readFileSync(join(directory, "package.json"), "utf8"), + ) as Record; + if ( + typeof metadata.name === "string" && + typeof metadata.version === "string" && + providesCli(metadata, cli) + ) + return { name: metadata.name, version: metadata.version }; + } catch { + // Not a package directory; keep walking up. + } + const parent = dirname(directory); + if (parent === directory) return undefined; + directory = parent; + } +}; + +/** The package the notice is about: the running one, with REA's version. */ +const updatePackage = (cli: string, version: string) => { + const running = runningPackage(cli); + return running === undefined || !isPackageName(running.name) + ? undefined + : { name: running.name, current: version }; +}; + +const cacheFile = ( + environment: UpdateEnvironment, + packageName: string, +): string | undefined => { + let root = variable(environment, "XDG_CACHE_HOME"); + if (!root) { + let home = variable( + environment, + environment.platform === "win32" ? "USERPROFILE" : "HOME", + ); + if (home === undefined) { + try { + // Match the child without consulting the parent's ambient HOME. + home = userInfo().homedir; + } catch { + // A notice is optional when the OS account has no readable home. + return undefined; + } + } + root = join(home, ".cache"); + } + return join( + root, + "incur", + "updates", + `${encodeURIComponent(packageName)}.json`, + ); +}; + +const readCache = (file: string): UpdateCache | undefined => { + try { + const value = JSON.parse(readFileSync(file, "utf8")) as Record< + string, + unknown + >; + if (typeof value.checkedAt !== "number") return undefined; + if (value.latest !== undefined && typeof value.latest !== "string") + return undefined; + return value as unknown as UpdateCache; + } catch { + return undefined; + } +}; + +const writeCache = (file: string, cache: UpdateCache): void => { + mkdirSync(dirname(file), { recursive: true }); + writeFileSync(file, `${JSON.stringify(cache)}\n`); +}; + +/** Run the refresh in a detached copy of this CLI that outlives the command. */ +const scheduleRefresh = ( + file: string, + checkedAt: number, + latest: string | undefined, + environment: UpdateEnvironment, +): void => { + const script = process.argv[1]; + if (!script) return; + let selfExecutable = script.startsWith("/$bunfs/"); + try { + selfExecutable ||= realpathSync(script) === realpathSync(process.execPath); + } catch { + // An unresolvable script still runs through the interpreter below. + } + const args = selfExecutable + ? [UPDATE_CHECK_FLAG] + : [...process.execArgv, script, UPDATE_CHECK_FLAG]; + try { + writeCache(file, { checkedAt, ...(latest ? { latest } : {}) }); + const child = spawn(process.execPath, args, { + detached: true, + stdio: "ignore", + env: environment.variables, + }); + child.once("error", () => {}); + child.unref(); + } catch { + // The notice never fails the command it follows. + } +}; + +/** + * A newer cached version, or undefined. Schedules a detached refresh when the + * cache is missing or older than a day. Callers ask only for terminal output + * without an explicit format. + */ +export const availableUpdate = ( + cli: string, + version: string, + environment: UpdateEnvironment, +): AvailableUpdate | undefined => { + if (notificationsDisabled(environment)) return undefined; + const target = updatePackage(cli, version); + if (target === undefined) return undefined; + const file = cacheFile(environment, target.name); + if (file === undefined) return undefined; + const cached = readCache(file); + const checkedAt = Date.now(); + if ( + cached === undefined || + checkedAt - cached.checkedAt >= REFRESH_INTERVAL_MS + ) + scheduleRefresh(file, checkedAt, cached?.latest, environment); + if (!cached?.latest || !isNewerVersion(cached.latest, target.current)) + return undefined; + return { name: target.name, current: target.current, latest: cached.latest }; +}; + +/** The notice's suggested-command block for an available update. */ +export const updateNoticeCta = (cli: string, update: AvailableUpdate) => ({ + description: `Update available for ${update.name}:`, + commands: [ + { + command: `${cli} --update`, + description: `upgrade from ${update.current} to ${update.latest}`, + }, + ], +}); + +/** The detached refresh: record the registry's latest version. Never throws. */ +export const refreshUpdateCache = async ( + cli: string, + version: string, + environment: UpdateEnvironment, +): Promise => { + try { + const target = updatePackage(cli, version); + if (target === undefined) return; + const file = cacheFile(environment, target.name); + if (file === undefined) return; + const registry = + variable(environment, "npm_config_registry") || + "https://registry.npmjs.org"; + const response = await fetch( + new URL( + encodeURIComponent(target.name), + registry.endsWith("/") ? registry : `${registry}/`, + ), + { + headers: { + accept: + "application/vnd.npm.install-v1+json; q=1.0, application/json; q=0.8, */*", + }, + signal: AbortSignal.timeout(REGISTRY_TIMEOUT_MS), + }, + ); + if (!response.ok) return; + const metadata = (await response.json()) as { + readonly "dist-tags"?: { readonly latest?: unknown }; + }; + const latest = metadata["dist-tags"]?.latest; + if (typeof latest !== "string" || parseVersion(latest) === undefined) + return; + writeCache(file, { + checkedAt: Date.now(), + latest, + }); + } catch { + // A failed refresh leaves the cache marked checked until the next day. + } +}; diff --git a/tests/boundary/cli/cliParityGoldens.test.ts b/tests/boundary/cli/cliParityGoldens.test.ts index 8906e4f9e7..2ea2eb4413 100644 --- a/tests/boundary/cli/cliParityGoldens.test.ts +++ b/tests/boundary/cli/cliParityGoldens.test.ts @@ -249,6 +249,14 @@ const CASES: readonly ParityCase[] = [ // Command resolution and argument errors { name: "error-unknown-command", arguments: fixed("no-such-command") }, { name: "error-empty-command", arguments: fixed("") }, + { + name: "error-unknown-command-full-output", + arguments: fixed("no-such-command", "--full-output", "--json"), + }, + { + name: "error-unknown-command-token-limit", + arguments: fixed("no-such-command", "--token-limit", "6"), + }, { name: "error-unknown-mcp-subcommand", arguments: fixed("mcp", "bogus") }, { name: "error-missing-positional", diff --git a/tests/boundary/cli/unknownCommandSensitivity.test.ts b/tests/boundary/cli/unknownCommandSensitivity.test.ts new file mode 100644 index 0000000000..d634e7f031 --- /dev/null +++ b/tests/boundary/cli/unknownCommandSensitivity.test.ts @@ -0,0 +1,138 @@ +import { expect } from "vitest"; + +import { HOST_PLATFORM } from "../../../src/platform/HostPlatform.js"; +import { cliTest } from "../../support/cli/cliFixture.js"; + +cliTest( + "MCP replies keep the existing default and explicit suggestion policies", + async ({ cli }) => { + const implicit = await cli.run({ arguments: ["mcp", "dctor"] }); + expect(implicit.exitCode).toBe(1); + expect(implicit.stdout).toContain("Did you mean 'doctor'?"); + const explicit = await cli.run({ arguments: ["mcp", "dctor", "--json"] }); + expect(explicit.exitCode).toBe(1); + expect(explicit.stdout).not.toContain("Did you mean"); + }, +); + +cliTest( + "unknown schema diagnostics exclude declared command names", + async ({ cli }) => { + const result = await cli.run({ + arguments: [ + "s3cret", + "--schema", + "--sensitive-value", + "s3cret", + "--json", + ], + }); + expect(result.exitCode).toBe(1); + expect(result.stdout).not.toContain("s3cret"); + expect(result.stdout).toContain("[REDACTED]"); + }, +); + +cliTest.skipIf(HOST_PLATFORM.platform === "win32")( + "terminal unknown-command guidance excludes declared values", + async ({ cli }) => { + for (const prefix of [[], ["mcp"]]) { + const result = await cli.run({ + arguments: [...prefix, "s3cret", "--sensitive-value", "s3cret"], + terminal: true, + }); + expect(result.exitCode).toBe(1); + expect(result.stdout).not.toContain("s3cret"); + expect(result.stdout).toContain("Error:"); + expect(result.stdout).toContain("[REDACTED]"); + } + }, +); + +cliTest( + "unknown-command diagnostics exclude declared values in every document format", + async ({ cli }) => { + const secret = "PRIVATE_VALUE"; + for (const format of ["json", "toon", "yaml", "md", "jsonl"]) { + const result = await cli.run({ + arguments: [ + "inspect-web-network-captur", + "capture.har", + "har", + "--sensitive-value", + secret, + "--format", + format, + ], + }); + expect(result.exitCode).toBe(1); + expect(result.stdout).not.toContain(secret); + expect(result.stdout).not.toContain("rea inspect-web-network-capture "); + expect(result.stdout).toContain("COMMAND_NOT_FOUND"); + } + }, +); + +cliTest( + "unknown names and fixed guidance honor declarations for root and MCP commands", + async ({ cli }) => { + for (const prefix of [[], ["mcp"]]) { + for (const format of [[], ["--json"], ["--json", "--full-output"]]) { + const result = await cli.run({ + arguments: [ + ...prefix, + "s3cret", + "--sensitive-value", + "s3cret", + "--sensitive-value=help", + ...format, + ], + }); + expect(result.exitCode).toBe(1); + expect(result.stdout).not.toContain("s3cret"); + expect(result.stdout).not.toContain("help"); + expect(result.stdout).toContain("[REDACTED]"); + } + } + }, +); + +cliTest( + "command corrections retain ordinary values and omit unsafe shell replays", + async ({ cli }) => { + const ordinary = await cli.run({ + arguments: [ + "inspect-web-network-captur", + "ordinary.har", + "har", + "--json", + ], + }); + expect(ordinary.exitCode).toBe(1); + expect(ordinary.stdout).toContain( + "rea inspect-web-network-capture ordinary.har har --json", + ); + const sameNameData = await cli.run({ + arguments: [ + "inspect-web-network-captur", + "inspect-web-network-captur", + "har", + "--json", + ], + }); + expect(sameNameData.stdout).toContain( + "rea inspect-web-network-capture inspect-web-network-captur har --json", + ); + const unsafe = await cli.run({ + arguments: [ + "inspect-web-network-captur", + "capture with spaces.har", + "har", + "--json", + ], + }); + expect(unsafe.exitCode).toBe(1); + expect(unsafe.stdout).not.toContain("rea inspect-web-network-capture "); + expect(unsafe.stdout).toContain("rea --help"); + }, +); diff --git a/tests/boundary/cli/updateCheckRefresh.test.ts b/tests/boundary/cli/updateCheckRefresh.test.ts new file mode 100644 index 0000000000..a6b10ca5b3 --- /dev/null +++ b/tests/boundary/cli/updateCheckRefresh.test.ts @@ -0,0 +1,80 @@ +import { once } from "node:events"; +import { readFile } from "node:fs/promises"; +import { createServer } from "node:http"; +import type { AddressInfo } from "node:net"; +import { expect } from "vitest"; + +import { PRODUCT_IDENTITY } from "../../../src/identity.js"; +import { cliTest } from "../../support/cli/cliFixture.js"; +import { + createTestWorkspace, + removeTestWorkspace, +} from "../../support/workspace/workspaceFixture.js"; + +const cacheFile = (root: string) => + `${root}/incur/updates/${encodeURIComponent(PRODUCT_IDENTITY.packageName)}.json`; + +cliTest( + "the detached update check records the registry's latest version in the update cache", + async ({ cli }) => { + const workspace = await createTestWorkspace("rea-update-check-"); + const requests: string[] = []; + const registry = createServer((request, response) => { + requests.push(request.url ?? ""); + response.setHeader("content-type", "application/json"); + response.end(JSON.stringify({ "dist-tags": { latest: "999.1.0" } })); + }); + registry.listen(0, "127.0.0.1"); + await once(registry, "listening"); + try { + const { port } = registry.address() as AddressInfo; + const result = await cli.run({ + arguments: ["--incur-update-check"], + freshProcess: true, + environment: { + ...workspace.environment, + XDG_CACHE_HOME: workspace.path("cache"), + npm_config_registry: `http://127.0.0.1:${port}/`, + }, + }); + expect(result).toMatchObject({ exitCode: 0, stdout: "", stderr: "" }); + expect(requests).toEqual([ + `/${encodeURIComponent(PRODUCT_IDENTITY.packageName)}`, + ]); + const cache = JSON.parse( + await readFile(cacheFile(workspace.path("cache")), "utf8"), + ) as { readonly checkedAt: unknown; readonly latest: unknown }; + expect(cache).toEqual({ + checkedAt: expect.any(Number), + latest: "999.1.0", + }); + } finally { + registry.close(); + await removeTestWorkspace(workspace.root); + } + }, +); + +cliTest( + "an unreachable registry leaves the update cache unwritten and the check silent", + async ({ cli }) => { + const workspace = await createTestWorkspace("rea-update-check-"); + try { + const result = await cli.run({ + arguments: ["--incur-update-check"], + freshProcess: true, + environment: { + ...workspace.environment, + XDG_CACHE_HOME: workspace.path("cache"), + npm_config_registry: "http://127.0.0.1:9/", + }, + }); + expect(result).toMatchObject({ exitCode: 0, stdout: "", stderr: "" }); + await expect( + readFile(cacheFile(workspace.path("cache")), "utf8"), + ).rejects.toMatchObject({ code: "ENOENT" }); + } finally { + await removeTestWorkspace(workspace.root); + } + }, +); diff --git a/tests/fixtures/cli-parity/error-unknown-command-full-output.txt b/tests/fixtures/cli-parity/error-unknown-command-full-output.txt new file mode 100644 index 0000000000..afbcc0f550 --- /dev/null +++ b/tests/fixtures/cli-parity/error-unknown-command-full-output.txt @@ -0,0 +1,7 @@ +$ rea no-such-command --full-output --json +exit: 1 +--- stdout +{"ok":false,"error":{"code":"COMMAND_NOT_FOUND","message":"'no-such-command' is not a command for 'rea'. Did you mean 'cutter-command'?"},"meta":{"command":"no-such-command","cta":{"description":"Suggested commands:","commands":[{"command":"rea cutter-command --full-output --json"},{"command":"rea --help","description":"see all available commands"}]},"duration":"ms"}} + +--- stderr + diff --git a/tests/fixtures/cli-parity/error-unknown-command-token-limit.txt b/tests/fixtures/cli-parity/error-unknown-command-token-limit.txt new file mode 100644 index 0000000000..bec56836c3 --- /dev/null +++ b/tests/fixtures/cli-parity/error-unknown-command-token-limit.txt @@ -0,0 +1,8 @@ +$ rea no-such-command --token-limit 6 +exit: 1 +--- stdout +code: COMMAND_NOT +[truncated: showing tokens 0–6 of 80] + +--- stderr + diff --git a/tests/process-global/updateNoticeEnvironment.test.ts b/tests/process-global/updateNoticeEnvironment.test.ts new file mode 100644 index 0000000000..5383441eed --- /dev/null +++ b/tests/process-global/updateNoticeEnvironment.test.ts @@ -0,0 +1,94 @@ +import childProcess, { ChildProcess } from "node:child_process"; +import { syncBuiltinESMExports } from "node:module"; +import { readFile } from "node:fs/promises"; +import { join, resolve } from "node:path"; +import { expect, it, vi } from "vitest"; + +import { createCliShell } from "../../src/cli/cliShell.js"; +import { PRODUCT_IDENTITY } from "../../src/identity.js"; +import { HOST_PLATFORM } from "../../src/platform/HostPlatform.js"; +import { snapshotEnvironment } from "../../src/process/snapshotEnvironment.js"; +import { createTestTempDirectory } from "../fixtures/temporaryDirectory.js"; + +it.each(["XDG cache", "home fallback"] as const)( + "schedules a stale notice refresh with the selected environment and %s", + async (source) => { + const root = await createTestTempDirectory("rea-notice-selected-env-"); + const selected = { + ...(source === "XDG cache" + ? { XDG_CACHE_HOME: join(root, "selected") } + : {}), + HOME: join(root, "selected-home"), + USERPROFILE: join(root, "selected-home"), + npm_config_registry: "http://127.0.0.1:9/selected/", + CI: "false", + NO_UPDATE_NOTIFIER: "", + SELECTED_SETTING: "original", + }; + const cli = createCliShell({ + selectedEnvironment: selected, + registrations: [], + }); + const expected = snapshotEnvironment(selected, HOST_PLATFORM.platform); + selected.SELECTED_SETTING = "changed after CLI construction"; + const argv = process.argv; + const exitCode = process.exitCode; + const tty = Object.getOwnPropertyDescriptor(process.stdout, "isTTY"); + const child = new ChildProcess(); + const spawn = vi.spyOn(childProcess, "spawn").mockReturnValue(child); + syncBuiltinESMExports(); + vi.stubEnv("XDG_CACHE_HOME", join(root, "ambient")); + vi.stubEnv("HOME", join(root, "ambient-home")); + vi.stubEnv("USERPROFILE", join(root, "ambient-home")); + vi.stubEnv("npm_config_registry", "http://127.0.0.1:9/ambient/"); + vi.stubEnv("AMBIENT_ONLY", "must not be inherited"); + try { + process.argv = [process.execPath, resolve("scripts/rea.mjs")]; + Object.defineProperty(process.stdout, "isTTY", { + configurable: true, + value: true, + }); + await cli.serve(["no-such-command"], { + stdout: () => {}, + exit: () => {}, + }); + expect(spawn).toHaveBeenCalledTimes(1); + expect(spawn.mock.calls[0]?.[2]).toMatchObject({ + detached: true, + stdio: "ignore", + env: expected, + }); + expect(spawn.mock.calls[0]?.[2]?.env).toEqual(expected); + const cache = join( + source === "XDG cache" + ? selected.XDG_CACHE_HOME! + : join(selected.HOME, ".cache"), + "incur", + "updates", + `${encodeURIComponent(PRODUCT_IDENTITY.packageName)}.json`, + ); + expect(JSON.parse(await readFile(cache, "utf8"))).toEqual({ + checkedAt: expect.any(Number), + }); + await expect( + readFile( + join( + root, + "ambient", + "incur", + "updates", + `${encodeURIComponent(PRODUCT_IDENTITY.packageName)}.json`, + ), + ), + ).rejects.toMatchObject({ code: "ENOENT" }); + } finally { + process.argv = argv; + process.exitCode = exitCode; + if (tty === undefined) Reflect.deleteProperty(process.stdout, "isTTY"); + else Object.defineProperty(process.stdout, "isTTY", tty); + vi.restoreAllMocks(); + syncBuiltinESMExports(); + vi.unstubAllEnvs(); + } + }, +);