@f5-sales-demo/xcsh 20.2.2 → 20.2.3

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [20.2.3] - 2026-08-02
+
+### Fixed
+
+- Made sandbox launch-flag scope errors consistent in either argument position, report usage exit 2 without parser exceptions, and direct operators to the flag-free conformance check ([#2834](https://github.com/f5-sales-demo/xcsh/issues/2834))
+
 ## [20.2.1] - 2026-08-01
 
 ### Fixed

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "20.2.2",
+	"version": "20.2.3",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5-sales-demo/xcsh",
 	"author": "Can Boluk",
@@ -57,13 +57,13 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "1.3.0",
 		"@mozilla/readability": "^0.6",
-		"@f5-sales-demo/xcsh-stats": "20.2.2",
-		"@f5-sales-demo/pi-agent-core": "20.2.2",
-		"@f5-sales-demo/pi-ai": "20.2.2",
-		"@f5-sales-demo/pi-natives": "20.2.2",
-		"@f5-sales-demo/pi-resource-management": "20.2.2",
-		"@f5-sales-demo/pi-tui": "20.2.2",
-		"@f5-sales-demo/pi-utils": "20.2.2",
+		"@f5-sales-demo/xcsh-stats": "20.2.3",
+		"@f5-sales-demo/pi-agent-core": "20.2.3",
+		"@f5-sales-demo/pi-ai": "20.2.3",
+		"@f5-sales-demo/pi-natives": "20.2.3",
+		"@f5-sales-demo/pi-resource-management": "20.2.3",
+		"@f5-sales-demo/pi-tui": "20.2.3",
+		"@f5-sales-demo/pi-utils": "20.2.3",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.20",

package/src/cli/flag-spec.ts

@@ -13,7 +13,7 @@
  * `cli/args.ts` can both depend on it without a cycle.
  */
 import { THINKING_EFFORTS } from "@f5-sales-demo/pi-ai";
-import { type FlagDescriptor, Flags } from "@f5-sales-demo/pi-utils/cli";
+import { CliUsageError, type FlagDescriptor, Flags } from "@f5-sales-demo/pi-utils/cli";
 
 export type FlagArity = "boolean" | "value" | "optional-value" | "repeatable-value";
 
@@ -157,8 +157,6 @@ export interface UnrecognizedFlag {
 	name: string;
 }
 
-export class FlagUsageError extends Error {}
-
 /**
  * Rewrite `--name=value` into `["--name", "value"]` for every flag that takes a value.
  *
@@ -197,7 +195,7 @@ export function normalizeFlagTokens(
 		const spec = flagSpec(name);
 		if (spec) {
 			if (!takesValue(spec)) {
-				throw new FlagUsageError(`--${name} is a boolean flag and does not take a value`);
+				throw new CliUsageError(`--${name} is a boolean flag and does not take a value`);
 			}
 			normalized.push(`--${name}`, value);
 			continue;
@@ -206,7 +204,7 @@ export function normalizeFlagTokens(
 		const extension = extensionFlags?.get(name);
 		if (extension) {
 			if (extension.type === "boolean") {
-				throw new FlagUsageError(`--${name} is a boolean flag and does not take a value`);
+				throw new CliUsageError(`--${name} is a boolean flag and does not take a value`);
 			}
 			normalized.push(`--${name}`, value);
 			continue;

package/src/cli/root-command-routing.ts

@@ -1,3 +1,4 @@
+import type { FlagDescriptor } from "@f5-sales-demo/pi-utils/cli";
 import { flagNameForChar, flagSpec, type LaunchFlagName } from "./flag-spec";
 
 export interface PrefixedCommandRoute {
@@ -6,6 +7,67 @@ export interface PrefixedCommandRoute {
 	prefixFlags: LaunchFlagName[];
 }
 
+function uniqueFlags(flags: readonly LaunchFlagName[]): LaunchFlagName[] {
+	return [...new Set(flags)];
+}
+
+/**
+ * Find agent-launch flags in a registered command's argv while preserving that command's own flags.
+ *
+ * `--` ends option parsing. Long and short command flags both take precedence over identically named
+ * launch flags, so `sandbox check -v` remains the sandbox check's verbose mode.
+ */
+export function findCommandLaunchFlags(
+	argv: readonly string[],
+	commandFlags: Readonly<Record<string, FlagDescriptor>>,
+): LaunchFlagName[] {
+	const shortCommandFlags = new Set(
+		Object.values(commandFlags)
+			.map(descriptor => descriptor.char)
+			.filter((char): char is string => char !== undefined),
+	);
+	const found: LaunchFlagName[] = [];
+
+	for (const token of argv) {
+		if (token === "--") break;
+		if (token.startsWith("--")) {
+			const name = token.slice(2).split("=", 1)[0];
+			if (commandFlags[name] !== undefined) continue;
+			if (flagSpec(name) !== undefined) found.push(name as LaunchFlagName);
+			continue;
+		}
+		if (!token.startsWith("-") || token === "-") continue;
+		const char = token.slice(1);
+		if (shortCommandFlags.has(char)) continue;
+		const name = flagNameForChar(char);
+		if (name !== undefined) found.push(name);
+	}
+
+	return uniqueFlags(found);
+}
+
+/** Render the single scope diagnostic used for launch flags on either side of a subcommand. */
+export function launchFlagScopeMessage(
+	flags: readonly LaunchFlagName[],
+	command: string,
+	commandArgs: readonly string[],
+	bin: string,
+): string {
+	const unique = uniqueFlags(flags);
+	const names = unique.map(flag => `--${flag}`).join(", ");
+	const singular = unique.length === 1;
+	if (command === "sandbox" && commandArgs[0] === "check") {
+		return (
+			`Launch ${singular ? "flag" : "flags"} ${names} ${singular ? "applies" : "apply"} to an agent session, not to \`sandbox check\`. ` +
+			`Run \`${bin} sandbox check\` without launch flags; its \`explicit grant restores parent enumeration\` probe verifies grant behavior.`
+		);
+	}
+	return (
+		`Launch ${singular ? "flag" : "flags"} ${names} ${singular ? "applies" : "apply"} to an agent session, not to the ` +
+		`\`${command}\` subcommand. Start an agent session with launch flags before its prompt.`
+	);
+}
+
 function optionalValue(token: string | undefined): token is string {
 	return token !== undefined && !token.startsWith("-") && !token.startsWith("@");
 }

package/src/cli.ts

@@ -5,8 +5,7 @@ import { APP_NAME, initI18n, MIN_BUN_VERSION, registerLocales, t, VERSION } from
  * lightweight CLI runner from pi-utils.
  */
 import { type CommandEntry, run } from "@f5-sales-demo/pi-utils/cli";
-import { FlagUsageError } from "./cli/flag-spec";
-import { findPrefixedCommand } from "./cli/root-command-routing";
+import { findPrefixedCommand, launchFlagScopeMessage } from "./cli/root-command-routing";
 import { locales } from "./locales/index";
 
 registerLocales(locales);
@@ -118,10 +117,13 @@ export function runCli(argv: string[]): Promise<void> {
 				help: showHelp,
 			});
 		}
-		const flags = [...new Set(prefixedCommand.prefixFlags)].map(flag => `--${flag}`).join(", ");
 		process.stderr.write(
-			`Error: launch ${prefixedCommand.prefixFlags.length === 1 ? "flag" : "flags"} ${flags} cannot precede the ` +
-				`\`${prefixedCommand.command}\` subcommand. Launch flags configure an agent session; subcommands must come first.\n`,
+			`Error: ${launchFlagScopeMessage(
+				prefixedCommand.prefixFlags,
+				prefixedCommand.command,
+				prefixedCommand.commandArgs,
+				APP_NAME,
+			)}\n`,
 		);
 		process.exitCode = 2;
 		return Promise.resolve();
@@ -152,10 +154,4 @@ if (process.env.XCSH_SMOKE_TEST_SPECS === "1") {
 	process.exit(domainCount > 0 && categoryCount > 0 ? 0 : 1);
 }
 
-try {
-	await runCli(process.argv.slice(2));
-} catch (error) {
-	if (!(error instanceof FlagUsageError)) throw error;
-	process.stderr.write(`Error: ${error.message}\n`);
-	process.exitCode = 2;
-}
+await runCli(process.argv.slice(2));

package/src/commands/sandbox.ts

@@ -1,5 +1,7 @@
 /** Run installed-binary sandbox diagnostics. */
-import { Args, Command, Flags } from "@f5-sales-demo/pi-utils/cli";
+import { APP_NAME } from "@f5-sales-demo/pi-utils";
+import { Args, CliUsageError, Command, Flags } from "@f5-sales-demo/pi-utils/cli";
+import { findCommandLaunchFlags, launchFlagScopeMessage } from "../cli/root-command-routing";
 import { runSandboxCheck } from "../cli/sandbox-check";
 
 export default class Sandbox extends Command {
@@ -19,6 +21,10 @@ export default class Sandbox extends Command {
 	};
 
 	async run(): Promise<void> {
+		const launchFlags = findCommandLaunchFlags(this.argv, Sandbox.flags);
+		if (launchFlags.length > 0) {
+			throw new CliUsageError(launchFlagScopeMessage(launchFlags, "sandbox", this.argv, APP_NAME));
+		}
 		const { flags } = await this.parse(Sandbox);
 		const report = await runSandboxCheck({ json: flags.json, verbose: flags.verbose });
 		if (report.summary.failed > 0 || report.summary.errors > 0) process.exitCode = 1;

package/src/internal-urls/build-info.generated.ts

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "20.2.2",
-	"commit": "fd7d7d7d2303d3d17149a84b2e1ceb8b743d3a4a",
-	"shortCommit": "fd7d7d7",
+	"version": "20.2.3",
+	"commit": "7f2e292bf69f563ff32c24c4faa787538aaab420",
+	"shortCommit": "7f2e292",
 	"branch": "main",
-	"tag": "v20.2.2",
-	"commitDate": "2026-08-02T01:16:07Z",
-	"buildDate": "2026-08-02T01:43:23.755Z",
+	"tag": "v20.2.3",
+	"commitDate": "2026-08-02T03:00:43Z",
+	"buildDate": "2026-08-02T03:26:38.179Z",
 	"dirty": true,
 	"prNumber": "",
 	"repoUrl": "https://github.com/f5-sales-demo/xcsh",
 	"repoSlug": "f5-sales-demo/xcsh",
-	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/fd7d7d7d2303d3d17149a84b2e1ceb8b743d3a4a",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v20.2.2"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/7f2e292bf69f563ff32c24c4faa787538aaab420",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v20.2.3"
 };