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(); + } + }, +);