@f5-sales-demo/xcsh 19.51.2

package/src/cli.ts

@@ -0,0 +1,123 @@
+#!/usr/bin/env bun
+import { APP_NAME, initI18n, MIN_BUN_VERSION, registerLocales, t, VERSION } from "@f5xc-salesdemos/pi-utils";
+/**
+ * CLI entry point — registers all commands explicitly and delegates to the
+ * lightweight CLI runner from pi-utils.
+ */
+import { type CommandEntry, run } from "@f5xc-salesdemos/pi-utils/cli";
+import { locales } from "./locales/index";
+
+registerLocales(locales);
+initI18n();
+
+function parseSemver(version: string): [number, number, number] {
+	function toint(value: string): number {
+		const int = Number.parseInt(value, 10);
+		if (Number.isNaN(int) || !Number.isFinite(int)) return 0;
+		return int;
+	}
+	const [majorRaw, minorRaw, patchRaw] = version.split(".").map(toint);
+	return [majorRaw, minorRaw, patchRaw];
+}
+
+function isAtLeastBunVersion(minimum: string): boolean {
+	const ver = parseSemver(Bun.version);
+	const min = parseSemver(minimum);
+	for (let i = 0; i < 3; i++) {
+		if (ver[i] !== min[i]) {
+			return ver[i] > min[i];
+		}
+	}
+	return true;
+}
+
+if (typeof Bun.JSONL?.parseChunk !== "function" || !isAtLeastBunVersion(MIN_BUN_VERSION)) {
+	process.stderr.write(
+		`${t("cli.errors.bunVersion", { minVersion: MIN_BUN_VERSION, currentVersion: Bun.version })}\n`,
+	);
+	process.exit(1);
+}
+
+// Detect known Bun errata that cause TUI crashes (e.g. Bun.stringWidth mishandling OSC sequences).
+if (Bun.stringWidth("\x1b[0m\x1b]8;;\x07") !== 0) {
+	process.stderr.write(`${t("cli.errors.bunErrata", { version: Bun.version })}\n`);
+	process.exit(1);
+}
+
+process.title = APP_NAME;
+
+const commands: CommandEntry[] = [
+	{ name: "launch", load: () => import("./commands/launch").then(m => m.default) },
+	{ name: "agents", load: () => import("./commands/agents").then(m => m.default) },
+	{ name: "commit", load: () => import("./commands/commit").then(m => m.default) },
+	{ name: "config", load: () => import("./commands/config").then(m => m.default) },
+	{ name: "chrome", load: () => import("./commands/chrome").then(m => m.default) },
+	{ name: "chrome-host", load: () => import("./commands/chrome-host").then(m => m.default) },
+	{ name: "grep", load: () => import("./commands/grep").then(m => m.default) },
+	{ name: "grievances", load: () => import("./commands/grievances").then(m => m.default) },
+	{ name: "read", load: () => import("./commands/read").then(m => m.default) },
+	{ name: "jupyter", load: () => import("./commands/jupyter").then(m => m.default) },
+	{ name: "plugin", load: () => import("./commands/plugin").then(m => m.default) },
+	{ name: "setup", load: () => import("./commands/setup").then(m => m.default) },
+	{ name: "shell", load: () => import("./commands/shell").then(m => m.default) },
+	{ name: "ssh", load: () => import("./commands/ssh").then(m => m.default) },
+	{ name: "stats", load: () => import("./commands/stats").then(m => m.default) },
+	{ name: "update", load: () => import("./commands/update").then(m => m.default) },
+	{ name: "search", load: () => import("./commands/web-search").then(m => m.default), aliases: ["q"] },
+];
+
+async function showHelp(config: import("@f5xc-salesdemos/pi-utils/cli").CliConfig): Promise<void> {
+	const { renderRootHelp } = await import("@f5xc-salesdemos/pi-utils/cli");
+	const { getExtraHelpText } = await import("./cli/args");
+	renderRootHelp(config);
+	const extra = getExtraHelpText();
+	if (extra.trim().length > 0) {
+		process.stdout.write(`\n${extra}\n`);
+	}
+}
+
+/**
+ * Determine whether argv[0] is a known subcommand name.
+ * If not, the entire argv is treated as args to the default "launch" command.
+ */
+function isSubcommand(first: string | undefined): boolean {
+	if (!first || first.startsWith("-") || first.startsWith("@")) return false;
+	return commands.some(e => e.name === first || e.aliases?.includes(first));
+}
+
+/** Run the CLI with the given argv (no `process.argv` prefix). */
+export function runCli(argv: string[]): Promise<void> {
+	// --help and --version are handled by run() directly, don't rewrite those.
+	// Everything else that isn't a known subcommand routes to "launch".
+	const first = argv[0];
+	const runArgv =
+		first === "--help" || first === "-h" || first === "--version" || first === "-v" || first === "help"
+			? argv
+			: isSubcommand(first)
+				? argv
+				: ["launch", ...argv];
+	return run({ bin: APP_NAME, version: VERSION, argv: runArgv, commands, help: showHelp });
+}
+
+if (process.env.XCSH_SMOKE_TEST_SPECS === "1") {
+	const specMod = require("./internal-urls/api-spec-index.generated") as { API_SPEC_INDEX?: { domains?: unknown[] } };
+	const catalogMod = require("./internal-urls/api-catalog-index.generated") as {
+		API_CATALOG_CATEGORY_SUMMARIES?: unknown[];
+	};
+	const domainCount = specMod.API_SPEC_INDEX?.domains?.length ?? 0;
+	const categoryCount = catalogMod.API_CATALOG_CATEGORY_SUMMARIES?.length ?? 0;
+	console.log(`api-specs: ${domainCount} domains, ${categoryCount} categories`);
+	process.exit(domainCount > 0 && categoryCount > 0 ? 0 : 1);
+}
+
+// The `chrome-host` native-messaging relay is a hot path — Chrome (re)launches it
+// on every (re)connect attempt. Skip language discovery (profile I/O + OS
+// collectors) for it: the relay never needs a locale, and running full init per
+// launch both wastes work and floods logs with "Applied locale" during reconnect
+// churn. Only the user-facing commands need language discovery.
+if (process.argv[2] !== "chrome-host") {
+	const { discoverAndApplyLanguage } = await import("./discovery/language");
+	await discoverAndApplyLanguage();
+}
+
+await runCli(process.argv.slice(2));

package/src/commands/agents.ts

@@ -0,0 +1,57 @@
+/**
+ * Manage bundled task agents.
+ */
+import { Args, Command, Flags, renderCommandHelp } from "@f5xc-salesdemos/pi-utils/cli";
+import { type AgentsAction, type AgentsCommandArgs, runAgentsCommand } from "../cli/agents-cli";
+import { initTheme } from "../modes/theme/theme";
+
+const ACTIONS: AgentsAction[] = ["unpack"];
+
+export default class Agents extends Command {
+	static description = "Manage bundled task agents";
+
+	static args = {
+		action: Args.string({
+			description: "Agents action",
+			required: false,
+			options: ACTIONS,
+		}),
+	};
+
+	static flags = {
+		force: Flags.boolean({ char: "f", description: "Overwrite existing agent files" }),
+		json: Flags.boolean({ description: "Output JSON" }),
+		dir: Flags.string({ description: "Output directory (overrides --user/--project)" }),
+		user: Flags.boolean({ description: "Write to ~/.xcsh/agent/agents (default)" }),
+		project: Flags.boolean({ description: "Write to ./.xcsh/agents" }),
+	};
+
+	static examples = [
+		"# Export bundled agents into user config (default)\n  xcsh agents unpack",
+		"# Export bundled agents into project config\n  xcsh agents unpack --project",
+		"# Overwrite existing local agent files\n  xcsh agents unpack --project --force",
+		"# Export into a custom directory\n  xcsh agents unpack --dir ./tmp/agents --json",
+	];
+
+	async run(): Promise<void> {
+		const { args, flags } = await this.parse(Agents);
+		if (!args.action) {
+			renderCommandHelp("xcsh", "agents", Agents);
+			return;
+		}
+
+		const cmd: AgentsCommandArgs = {
+			action: args.action as AgentsAction,
+			flags: {
+				force: flags.force,
+				json: flags.json,
+				dir: flags.dir,
+				user: flags.user,
+				project: flags.project,
+			},
+		};
+
+		await initTheme();
+		await runAgentsCommand(cmd);
+	}
+}

package/src/commands/chrome-host.ts

@@ -0,0 +1,71 @@
+/**
+ * `chrome-host` — native-messaging relay subcommand.
+ *
+ * Launched by Chrome as the native-messaging host. It is a pure relay between
+ * Chrome's stdio (native-messaging framing: 4-byte LE length + JSON) and xcsh's
+ * Unix socket at `~/.xcsh/chrome-bridge.sock` (newline-delimited JSON). No
+ * business logic lives here.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { Command } from "@f5xc-salesdemos/pi-utils/cli";
+import { decodeNm, encodeNm } from "../browser/native-messaging";
+
+const SOCKET_PATH = process.env.XCSH_BRIDGE_SOCKET ?? join(homedir(), ".xcsh", "chrome-bridge.sock");
+
+export default class ChromeHost extends Command {
+	static description = "Native-messaging relay between Chrome and the xcsh bridge socket (internal)";
+
+	async run(): Promise<void> {
+		let socket: Awaited<ReturnType<typeof Bun.connect>> | undefined;
+		let socketBuffer = "";
+
+		try {
+			socket = await Bun.connect({
+				unix: SOCKET_PATH,
+				socket: {
+					data(_sock, chunk) {
+						// Socket → Chrome: NDJSON lines → native-messaging frames.
+						socketBuffer += new TextDecoder().decode(chunk);
+						let newlineIndex = socketBuffer.indexOf("\n");
+						while (newlineIndex !== -1) {
+							const line = socketBuffer.slice(0, newlineIndex);
+							socketBuffer = socketBuffer.slice(newlineIndex + 1);
+							if (line.length > 0) {
+								process.stdout.write(encodeNm(JSON.parse(line)));
+							}
+							newlineIndex = socketBuffer.indexOf("\n");
+						}
+					},
+					close() {
+						process.exit(0);
+					},
+					error() {
+						process.exit(0);
+					},
+				},
+			});
+		} catch {
+			// xcsh not running — write nothing, exit cleanly. The extension retries.
+			process.exit(0);
+		}
+
+		// Chrome stdin → socket: native-messaging frames → NDJSON lines.
+		let stdinBuffer: Uint8Array<ArrayBufferLike> = new Uint8Array(0);
+		for await (const chunk of process.stdin) {
+			const bytes = new Uint8Array(chunk);
+			const next = new Uint8Array(stdinBuffer.length + bytes.length);
+			next.set(stdinBuffer, 0);
+			next.set(bytes, stdinBuffer.length);
+			const { messages, rest } = decodeNm(next);
+			stdinBuffer = rest;
+			for (const msg of messages) {
+				socket.write(`${JSON.stringify(msg)}\n`);
+			}
+		}
+
+		// Chrome closed stdin — tear down and exit.
+		socket.end();
+		process.exit(0);
+	}
+}

package/src/commands/chrome.ts

@@ -0,0 +1,28 @@
+/**
+ * Inspect or arrange the Chrome session xcsh drives for console automation.
+ */
+import { Args, Command } from "@f5xc-salesdemos/pi-utils/cli";
+import { type ChromeAction, runChromeCommand } from "../cli/chrome-cli";
+import { Settings, settings } from "../config/settings";
+
+const ACTIONS: ChromeAction[] = ["status", "relaunch", "setup"];
+
+export default class Chrome extends Command {
+	static description = "Inspect or arrange the Chrome session xcsh drives for console automation";
+
+	static args = {
+		action: Args.string({
+			description: "status | relaunch | setup",
+			required: false,
+			options: ACTIONS,
+		}),
+	};
+
+	async run(): Promise<void> {
+		const { args } = await this.parse(Chrome);
+		const action = (args.action ?? "status") as ChromeAction;
+		await Settings.init();
+		// eslint-disable-next-line no-console
+		console.log(await runChromeCommand(action, settings));
+	}
+}

package/src/commands/commit.ts

@@ -0,0 +1,36 @@
+/**
+ * Generate and optionally push a commit with changelog updates.
+ */
+import { Command, Flags } from "@f5xc-salesdemos/pi-utils/cli";
+import { runCommitCommand } from "../commit";
+import type { CommitCommandArgs } from "../commit/types";
+import { initTheme } from "../modes/theme/theme";
+
+export default class Commit extends Command {
+	static description = "Generate a commit message and update changelogs";
+
+	static flags = {
+		push: Flags.boolean({ description: "Push after committing" }),
+		"dry-run": Flags.boolean({ description: "Preview without committing" }),
+		"no-changelog": Flags.boolean({ description: "Skip changelog updates" }),
+		legacy: Flags.boolean({ description: "Use legacy deterministic pipeline" }),
+		context: Flags.string({ char: "c", description: "Additional context for the model" }),
+		model: Flags.string({ char: "m", description: "Override model selection" }),
+	};
+
+	async run(): Promise<void> {
+		const { flags } = await this.parse(Commit);
+
+		const cmd: CommitCommandArgs = {
+			push: flags.push ?? false,
+			dryRun: flags["dry-run"] ?? false,
+			noChangelog: flags["no-changelog"] ?? false,
+			legacy: flags.legacy,
+			context: flags.context,
+			model: flags.model,
+		};
+
+		await initTheme();
+		await runCommitCommand(cmd);
+	}
+}

package/src/commands/config.ts

@@ -0,0 +1,51 @@
+/**
+ * Manage configuration settings.
+ */
+import { Args, Command, Flags } from "@f5xc-salesdemos/pi-utils/cli";
+import { type ConfigAction, type ConfigCommandArgs, runConfigCommand } from "../cli/config-cli";
+import { initTheme } from "../modes/theme/theme";
+
+const ACTIONS: ConfigAction[] = ["list", "get", "set", "reset", "path", "init-xdg"];
+
+export default class Config extends Command {
+	static description = "Manage configuration settings";
+
+	static args = {
+		action: Args.string({
+			description: "Config action",
+			required: false,
+			options: ACTIONS,
+		}),
+		key: Args.string({
+			description: "Setting key",
+			required: false,
+		}),
+		value: Args.string({
+			description: "Value (for set/reset)",
+			required: false,
+			multiple: true,
+		}),
+	};
+
+	static flags = {
+		json: Flags.boolean({ description: "Output JSON" }),
+	};
+
+	async run(): Promise<void> {
+		const { args, flags } = await this.parse(Config);
+		const action = (args.action ?? "list") as ConfigAction;
+		const value = Array.isArray(args.value) ? args.value.join(" ") : args.value;
+
+		const cmd: ConfigCommandArgs = {
+			action,
+			key: args.key,
+			value,
+			flags: {
+				json: flags.json,
+			},
+		};
+
+		await initTheme();
+		await runConfigCommand(cmd);
+	}
+}

package/src/commands/grep.ts

@@ -0,0 +1,48 @@
+/**
+ * Test grep tool.
+ */
+import { GrepOutputMode } from "@f5xc-salesdemos/pi-natives";
+import { Args, Command, Flags } from "@f5xc-salesdemos/pi-utils/cli";
+import { type GrepCommandArgs, runGrepCommand } from "../cli/grep-cli";
+import { initTheme } from "../modes/theme/theme";
+
+export default class Grep extends Command {
+	static description = "Test grep tool";
+
+	static args = {
+		pattern: Args.string({ description: "Regex pattern to search for", required: false }),
+		path: Args.string({ description: "Directory or file to search", required: false }),
+	};
+
+	static flags = {
+		glob: Flags.string({ char: "g", description: "Filter files by glob pattern" }),
+		limit: Flags.integer({ char: "l", description: "Max matches", default: 20 }),
+		context: Flags.integer({ char: "C", description: "Context lines", default: 2 }),
+		files: Flags.boolean({ char: "f", description: "Output file names only" }),
+		count: Flags.boolean({ char: "c", description: "Output match counts per file" }),
+		"no-gitignore": Flags.boolean({ description: "Include files excluded by .gitignore" }),
+	};
+
+	async run(): Promise<void> {
+		const { args, flags } = await this.parse(Grep);
+
+		const mode: GrepCommandArgs["mode"] = flags.count
+			? GrepOutputMode.Count
+			: flags.files
+				? GrepOutputMode.FilesWithMatches
+				: GrepOutputMode.Content;
+
+		const cmd: GrepCommandArgs = {
+			pattern: args.pattern ?? "",
+			path: args.path ?? ".",
+			glob: flags.glob,
+			limit: flags.limit,
+			context: flags.context,
+			mode,
+			gitignore: !flags["no-gitignore"],
+		};
+
+		await initTheme();
+		await runGrepCommand(cmd);
+	}
+}

package/src/commands/grievances.ts

@@ -0,0 +1,20 @@
+/**
+ * View recently reported tool issues from automated QA.
+ */
+import { Command, Flags } from "@f5xc-salesdemos/pi-utils/cli";
+import { listGrievances } from "../cli/grievances-cli";
+
+export default class Grievances extends Command {
+	static description = "View reported tool issues (auto-QA grievances)";
+
+	static flags = {
+		limit: Flags.integer({ char: "n", description: "Number of recent issues to show", default: 20 }),
+		tool: Flags.string({ char: "t", description: "Filter by tool name" }),
+		json: Flags.boolean({ char: "j", description: "Output as JSON", default: false }),
+	};
+
+	async run(): Promise<void> {
+		const { flags } = await this.parse(Grievances);
+		await listGrievances({ limit: flags.limit, tool: flags.tool, json: flags.json });
+	}
+}

package/src/commands/jupyter.ts

@@ -0,0 +1,32 @@
+/**
+ * Manage the shared Jupyter gateway.
+ */
+import { Args, Command } from "@f5xc-salesdemos/pi-utils/cli";
+import { type JupyterAction, type JupyterCommandArgs, runJupyterCommand } from "../cli/jupyter-cli";
+import { initTheme } from "../modes/theme/theme";
+
+const ACTIONS: JupyterAction[] = ["kill", "status"];
+
+export default class Jupyter extends Command {
+	static description = "Manage the shared Jupyter gateway";
+
+	static args = {
+		action: Args.string({
+			description: "Jupyter action",
+			required: false,
+			options: ACTIONS,
+		}),
+	};
+
+	async run(): Promise<void> {
+		const { args } = await this.parse(Jupyter);
+		const action = (args.action ?? "status") as JupyterAction;
+
+		const cmd: JupyterCommandArgs = {
+			action,
+		};
+
+		await initTheme();
+		await runJupyterCommand(cmd);
+	}
+}

package/src/commands/launch.ts

@@ -0,0 +1,144 @@
+/**
+ * Root command for the coding agent CLI.
+ */
+
+import { THINKING_EFFORTS } from "@f5xc-salesdemos/pi-ai";
+import { APP_NAME } from "@f5xc-salesdemos/pi-utils";
+import { Args, Command, Flags } from "@f5xc-salesdemos/pi-utils/cli";
+import { parseArgs } from "../cli/args";
+import { runRootCommand } from "../main";
+
+export default class Index extends Command {
+	static description = "AI coding assistant";
+	static hidden = true;
+
+	static args = {
+		messages: Args.string({
+			description: "Messages to send (prefix files with @)",
+			required: false,
+			multiple: true,
+		}),
+	};
+
+	static flags = {
+		model: Flags.string({
+			description: 'Model to use (fuzzy match: "opus", "gpt-5.2", or "p-openai/gpt-5.2")',
+		}),
+		smol: Flags.string({
+			description: "Smol/fast model for lightweight tasks (or PI_SMOL_MODEL env)",
+		}),
+		slow: Flags.string({
+			description: "Slow/reasoning model for thorough analysis (or PI_SLOW_MODEL env)",
+		}),
+		plan: Flags.string({
+			description: "Plan model for architectural planning (or PI_PLAN_MODEL env)",
+		}),
+		provider: Flags.string({
+			description: "Provider to use (legacy; prefer --model)",
+		}),
+		"api-key": Flags.string({
+			description: "API key (defaults to env vars)",
+		}),
+		"system-prompt": Flags.string({
+			description: "System prompt (default: coding assistant prompt)",
+		}),
+		"append-system-prompt": Flags.string({
+			description: "Append text or file contents to the system prompt",
+		}),
+		"allow-home": Flags.boolean({
+			description: "Allow starting in ~ without auto-switching to a temp dir",
+		}),
+		mode: Flags.string({
+			description: "Output mode: text (default), json, or rpc",
+			options: ["text", "json", "rpc"],
+		}),
+		print: Flags.boolean({
+			char: "p",
+			description: "Non-interactive mode: process prompt and exit",
+		}),
+		continue: Flags.boolean({
+			char: "c",
+			description: "Continue previous session",
+		}),
+		resume: Flags.string({
+			char: "r",
+			description: "Resume a session (by ID prefix, path, or picker if omitted)",
+		}),
+		"session-dir": Flags.string({
+			description: "Directory for session storage and lookup",
+		}),
+		"no-session": Flags.boolean({
+			description: "Don't save session (ephemeral)",
+		}),
+		models: Flags.string({
+			description: "Comma-separated model patterns for Ctrl+P cycling",
+		}),
+		"no-tools": Flags.boolean({
+			description: "Disable all built-in tools",
+		}),
+		"no-mcp": Flags.boolean({
+			description: "Disable MCP server discovery and tools",
+		}),
+		"no-lsp": Flags.boolean({
+			description: "Disable LSP tools, formatting, and diagnostics",
+		}),
+		"no-pty": Flags.boolean({
+			description: "Disable PTY-based interactive bash execution",
+		}),
+		tools: Flags.string({
+			description: "Comma-separated list of tools to enable (default: all)",
+		}),
+		thinking: Flags.string({
+			description: `Set thinking level: ${THINKING_EFFORTS.join(", ")}`,
+			options: [...THINKING_EFFORTS],
+		}),
+		hook: Flags.string({
+			description: "Load a hook/extension file (can be used multiple times)",
+			multiple: true,
+		}),
+		extension: Flags.string({
+			char: "e",
+			description: "Load an extension file (can be used multiple times)",
+			multiple: true,
+		}),
+		"no-extensions": Flags.boolean({
+			description: "Disable extension discovery (explicit -e paths still work)",
+		}),
+		"no-skills": Flags.boolean({
+			description: "Disable skills discovery and loading",
+		}),
+		skills: Flags.string({
+			description: "Comma-separated glob patterns to filter skills (e.g., git-*,docker)",
+		}),
+		"no-rules": Flags.boolean({
+			description: "Disable rules discovery and loading",
+		}),
+		export: Flags.string({
+			description: "Export session file to HTML and exit",
+		}),
+		"list-models": Flags.string({
+			description: "List available models (with optional fuzzy search)",
+		}),
+		"no-title": Flags.boolean({
+			description: "Disable title auto-generation",
+		}),
+	};
+
+	static examples = [
+		`# Interactive mode\n  ${APP_NAME}`,
+		`# Interactive mode with initial prompt\n  ${APP_NAME} "List all .ts files in src/"`,
+		`# Include files in initial message\n  ${APP_NAME} @prompt.md @image.png "What color is the sky?"`,
+		`# Non-interactive mode (process and exit)\n  ${APP_NAME} -p "List all .ts files in src/"`,
+		`# Continue previous session\n  ${APP_NAME} --continue "What did we discuss?"`,
+		`# Use different model (fuzzy matching)\n  ${APP_NAME} --model opus "Help me refactor this code"`,
+		`# Limit model cycling to specific models\n  ${APP_NAME} --models claude-sonnet,claude-haiku,gpt-4o`,
+		`# Export a session file to HTML\n  ${APP_NAME} --export ~/.xcsh/agent/sessions/--path--/session.jsonl`,
+	];
+
+	static strict = false;
+
+	async run(): Promise<void> {
+		const parsed = parseArgs(this.argv);
+		await runRootCommand(parsed, this.argv);
+	}
+}