@f5xc-salesdemos/xcsh 2.2.0 → 14.0.2

package/src/cli/agents-cli.ts

@@ -0,0 +1,138 @@
+/**
+ * Agents CLI command handlers.
+ *
+ * Handles `xcsh agents unpack` for writing bundled agent definitions to disk.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { getAgentDir, getProjectDir, isEnoent } from "@f5xc-salesdemos/pi-utils";
+import { YAML } from "bun";
+import chalk from "chalk";
+import { theme } from "../modes/theme/theme";
+import { loadBundledAgents } from "../task/agents";
+import type { AgentDefinition } from "../task/types";
+
+export type AgentsAction = "unpack";
+
+export interface AgentsCommandArgs {
+	action: AgentsAction;
+	flags: {
+		force?: boolean;
+		json?: boolean;
+		dir?: string;
+		user?: boolean;
+		project?: boolean;
+	};
+}
+
+interface UnpackResult {
+	targetDir: string;
+	total: number;
+	written: string[];
+	skipped: string[];
+}
+
+function writeStdout(line: string): void {
+	process.stdout.write(`${line}\n`);
+}
+
+function resolveTargetDir(flags: AgentsCommandArgs["flags"]): string {
+	if (flags.dir && flags.dir.trim().length > 0) {
+		return path.resolve(getProjectDir(), flags.dir.trim());
+	}
+
+	if (flags.user && flags.project) {
+		throw new Error("Choose either --user or --project, not both.");
+	}
+
+	if (flags.project) {
+		return path.resolve(getProjectDir(), ".xcsh", "agents");
+	}
+
+	return path.join(getAgentDir(), "agents");
+}
+
+function toFrontmatter(agent: AgentDefinition): Record<string, unknown> {
+	const frontmatter: Record<string, unknown> = {
+		name: agent.name,
+		description: agent.description,
+	};
+
+	if (agent.tools && agent.tools.length > 0) frontmatter.tools = agent.tools;
+	if (agent.spawns !== undefined) frontmatter.spawns = agent.spawns;
+	if (agent.model && agent.model.length > 0) frontmatter.model = agent.model;
+	if (agent.thinkingLevel) frontmatter.thinkingLevel = agent.thinkingLevel;
+	if (agent.output !== undefined) frontmatter.output = agent.output;
+	if (agent.blocking) frontmatter.blocking = true;
+
+	return frontmatter;
+}
+
+function serializeAgent(agent: AgentDefinition): string {
+	const frontmatter = YAML.stringify(toFrontmatter(agent), null, 2).trimEnd();
+	const body = agent.systemPrompt.trim();
+	return `---\n${frontmatter}\n---\n\n${body}\n`;
+}
+
+async function unpackBundledAgents(flags: AgentsCommandArgs["flags"]): Promise<UnpackResult> {
+	const targetDir = resolveTargetDir(flags);
+	await fs.mkdir(targetDir, { recursive: true });
+
+	const bundledAgents = [...loadBundledAgents()].sort((a, b) => a.name.localeCompare(b.name));
+	const written: string[] = [];
+	const skipped: string[] = [];
+
+	for (const agent of bundledAgents) {
+		const filePath = path.join(targetDir, `${agent.name}.md`);
+		if (!flags.force) {
+			try {
+				await fs.stat(filePath);
+				skipped.push(filePath);
+				continue;
+			} catch (error) {
+				if (!isEnoent(error)) throw error;
+			}
+		}
+
+		await Bun.write(filePath, serializeAgent(agent));
+		written.push(filePath);
+	}
+
+	return {
+		targetDir,
+		total: bundledAgents.length,
+		written,
+		skipped,
+	};
+}
+
+export async function runAgentsCommand(cmd: AgentsCommandArgs): Promise<void> {
+	switch (cmd.action) {
+		case "unpack": {
+			const result = await unpackBundledAgents(cmd.flags);
+			if (cmd.flags.json) {
+				writeStdout(JSON.stringify(result, null, 2));
+				return;
+			}
+
+			writeStdout(chalk.bold(`Bundled agents: ${result.total}`));
+			writeStdout(chalk.dim(`Target directory: ${result.targetDir}`));
+			writeStdout(chalk.green(`${theme.status.success} Written: ${result.written.length}`));
+			if (result.skipped.length > 0) {
+				writeStdout(
+					chalk.yellow(
+						`${theme.status.warning} Skipped existing: ${result.skipped.length} (use --force to overwrite)`,
+					),
+				);
+			}
+
+			for (const filePath of result.written) {
+				writeStdout(chalk.dim(`  + ${filePath}`));
+			}
+			for (const filePath of result.skipped) {
+				writeStdout(chalk.dim(`  = ${filePath}`));
+			}
+			return;
+		}
+	}
+}

package/src/cli/args.ts

@@ -0,0 +1,283 @@
+/**
+ * CLI argument parsing and help display
+ */
+import { type Effort, THINKING_EFFORTS } from "@f5xc-salesdemos/pi-ai";
+import { APP_NAME, CONFIG_DIR_NAME, logger } from "@f5xc-salesdemos/pi-utils";
+import chalk from "chalk";
+import { parseEffort } from "../thinking";
+import { BUILTIN_TOOLS } from "../tools";
+
+export type Mode = "text" | "json" | "rpc" | "acp";
+
+export interface Args {
+	cwd?: string;
+	allowHome?: boolean;
+	provider?: string;
+	model?: string;
+	smol?: string;
+	slow?: string;
+	plan?: string;
+	apiKey?: string;
+	systemPrompt?: string;
+	appendSystemPrompt?: string;
+	thinking?: Effort;
+	continue?: boolean;
+	resume?: string | true;
+	help?: boolean;
+	version?: boolean;
+	mode?: Mode;
+	noSession?: boolean;
+	sessionDir?: string;
+	providerSessionId?: string;
+	fork?: string;
+	models?: string[];
+	tools?: string[];
+	noTools?: boolean;
+	noLsp?: boolean;
+	noPty?: boolean;
+	hooks?: string[];
+	extensions?: string[];
+	noExtensions?: boolean;
+	pluginDirs?: string[];
+	print?: boolean;
+	export?: string;
+	noSkills?: boolean;
+	skills?: string[];
+	noRules?: boolean;
+	listModels?: string | true;
+	noTitle?: boolean;
+	messages: string[];
+	fileArgs: string[];
+	/** Unknown flags (potentially extension flags) - map of flag name to value */
+	unknownFlags: Map<string, boolean | string>;
+}
+
+export function parseArgs(args: string[], extensionFlags?: Map<string, { type: "boolean" | "string" }>): Args {
+	const result: Args = {
+		messages: [],
+		fileArgs: [],
+		unknownFlags: new Map(),
+	};
+
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+
+		if (arg === "--help" || arg === "-h") {
+			result.help = true;
+		} else if (arg === "--version" || arg === "-v") {
+			result.version = true;
+		} else if (arg === "--allow-home") {
+			result.allowHome = true;
+		} else if (arg === "--mode" && i + 1 < args.length) {
+			const mode = args[++i];
+			if (mode === "text" || mode === "json" || mode === "rpc" || mode === "acp") {
+				result.mode = mode;
+			}
+		} else if (arg === "--continue" || arg === "-c") {
+			result.continue = true;
+		} else if (arg === "--resume" || arg === "-r" || arg === "--session") {
+			const next = args[i + 1];
+			if (next && !next.startsWith("-")) {
+				result.resume = args[++i];
+			} else {
+				result.resume = true;
+			}
+		} else if (arg === "--fork" && i + 1 < args.length) {
+			result.fork = args[++i];
+		} else if (arg === "--provider" && i + 1 < args.length) {
+			result.provider = args[++i];
+		} else if (arg === "--model" && i + 1 < args.length) {
+			result.model = args[++i];
+		} else if (arg === "--smol" && i + 1 < args.length) {
+			result.smol = args[++i];
+		} else if (arg === "--slow" && i + 1 < args.length) {
+			result.slow = args[++i];
+		} else if (arg === "--plan" && i + 1 < args.length) {
+			result.plan = args[++i];
+		} else if (arg === "--api-key" && i + 1 < args.length) {
+			result.apiKey = args[++i];
+		} else if (arg === "--system-prompt" && i + 1 < args.length) {
+			result.systemPrompt = args[++i];
+		} else if (arg === "--append-system-prompt" && i + 1 < args.length) {
+			result.appendSystemPrompt = args[++i];
+		} else if (arg === "--provider-session-id" && i + 1 < args.length) {
+			result.providerSessionId = args[++i];
+		} else if (arg === "--no-session") {
+			result.noSession = true;
+		} else if (arg === "--session-dir" && i + 1 < args.length) {
+			result.sessionDir = args[++i];
+		} else if (arg === "--models" && i + 1 < args.length) {
+			result.models = args[++i].split(",").map(s => s.trim());
+		} else if (arg === "--no-tools") {
+			result.noTools = true;
+		} else if (arg === "--no-lsp") {
+			result.noLsp = true;
+		} else if (arg === "--no-pty") {
+			result.noPty = true;
+		} else if (arg === "--tools" && i + 1 < args.length) {
+			const toolNames = args[++i]
+				.split(",")
+				.map(s => s.trim().toLowerCase())
+				.filter(Boolean);
+			const validTools: string[] = [];
+			for (const name of toolNames) {
+				if (name in BUILTIN_TOOLS) {
+					validTools.push(name);
+				} else {
+					logger.warn("Unknown tool passed to --tools", {
+						tool: name,
+						validTools: Object.keys(BUILTIN_TOOLS),
+					});
+				}
+			}
+			result.tools = validTools;
+		} else if (arg === "--thinking" && i + 1 < args.length) {
+			const rawThinking = args[++i];
+			const thinking = parseEffort(rawThinking);
+			if (thinking !== undefined) {
+				result.thinking = thinking;
+			} else {
+				logger.warn("Invalid thinking level passed to --thinking", {
+					level: rawThinking,
+					validThinkingLevels: THINKING_EFFORTS,
+				});
+			}
+		} else if (arg === "--print" || arg === "-p") {
+			result.print = true;
+		} else if (arg === "--export" && i + 1 < args.length) {
+			result.export = args[++i];
+		} else if (arg === "--hook" && i + 1 < args.length) {
+			result.hooks = result.hooks ?? [];
+			result.hooks.push(args[++i]);
+		} else if ((arg === "--extension" || arg === "-e") && i + 1 < args.length) {
+			result.extensions = result.extensions ?? [];
+			result.extensions.push(args[++i]);
+		} else if (arg === "--plugin-dir" && i + 1 < args.length) {
+			result.pluginDirs = result.pluginDirs ?? [];
+			result.pluginDirs.push(args[++i]);
+		} else if (arg === "--no-extensions") {
+			result.noExtensions = true;
+		} else if (arg === "--no-skills") {
+			result.noSkills = true;
+		} else if (arg === "--no-rules") {
+			result.noRules = true;
+		} else if (arg === "--no-title") {
+			result.noTitle = true;
+		} else if (arg === "--skills" && i + 1 < args.length) {
+			// Comma-separated glob patterns for skill filtering
+			result.skills = args[++i].split(",").map(s => s.trim());
+		} else if (arg === "--list-models") {
+			// Check if next arg is a search pattern (not a flag or file arg)
+			if (i + 1 < args.length && !args[i + 1].startsWith("-") && !args[i + 1].startsWith("@")) {
+				result.listModels = args[++i];
+			} else {
+				result.listModels = true;
+			}
+		} else if (arg.startsWith("@")) {
+			result.fileArgs.push(arg.slice(1)); // Remove @ prefix
+		} else if (arg.startsWith("--") && extensionFlags) {
+			// Check if it's an extension-registered flag
+			const flagName = arg.slice(2);
+			const extFlag = extensionFlags.get(flagName);
+			if (extFlag) {
+				if (extFlag.type === "boolean") {
+					result.unknownFlags.set(flagName, true);
+				} else if (extFlag.type === "string" && i + 1 < args.length) {
+					result.unknownFlags.set(flagName, args[++i]);
+				}
+			}
+			// Unknown flags without extensionFlags are silently ignored (first pass)
+		} else if (!arg.startsWith("-")) {
+			result.messages.push(arg);
+		}
+	}
+
+	return result;
+}
+
+export function getExtraHelpText(): string {
+	return `${chalk.bold("Environment Variables:")}
+  ${chalk.dim("# Core Providers")}
+  ANTHROPIC_API_KEY          - Anthropic Claude models
+  ANTHROPIC_OAUTH_TOKEN      - Anthropic OAuth (takes precedence over API key)
+  CLAUDE_CODE_USE_FOUNDRY    - Enable Anthropic Foundry mode (uses Foundry endpoint + mTLS)
+  FOUNDRY_BASE_URL           - Anthropic Foundry base URL (e.g., https://<foundry-host>)
+  ANTHROPIC_FOUNDRY_API_KEY  - Anthropic token used as Authorization: Bearer <token> in Foundry mode
+  ANTHROPIC_CUSTOM_HEADERS   - Extra Foundry headers (e.g., "user-id: USERNAME")
+  CLAUDE_CODE_CLIENT_CERT    - Client certificate (PEM path or inline PEM) for mTLS
+  CLAUDE_CODE_CLIENT_KEY     - Client private key (PEM path or inline PEM) for mTLS
+  NODE_EXTRA_CA_CERTS        - CA bundle path (or inline PEM) for server certificate validation
+  OPENAI_API_KEY             - OpenAI GPT models
+  GEMINI_API_KEY             - Google Gemini models
+  GITHUB_TOKEN               - GitHub Copilot (or GH_TOKEN, COPILOT_GITHUB_TOKEN)
+
+  ${chalk.dim("# Additional LLM Providers")}
+  AZURE_OPENAI_API_KEY       - Azure OpenAI models
+  GROQ_API_KEY               - Groq models
+  CEREBRAS_API_KEY           - Cerebras models
+  XAI_API_KEY                - xAI Grok models
+  OPENROUTER_API_KEY         - OpenRouter aggregated models
+  KILO_API_KEY               - Kilo Gateway models
+  MISTRAL_API_KEY            - Mistral models
+  ZAI_API_KEY                - z.ai models (ZhipuAI/GLM)
+  MINIMAX_API_KEY            - MiniMax models
+  OPENCODE_API_KEY           - OpenCode Zen/OpenCode Go models
+  CURSOR_ACCESS_TOKEN        - Cursor AI models
+  AI_GATEWAY_API_KEY         - Vercel AI Gateway
+
+  ${chalk.dim("# Cloud Providers")}
+  AWS_PROFILE                - AWS Bedrock (or AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY)
+  GOOGLE_CLOUD_PROJECT       - Google Vertex AI (requires GOOGLE_CLOUD_LOCATION)
+  GOOGLE_APPLICATION_CREDENTIALS - Service account for Vertex AI
+
+  ${chalk.dim("# Search & Tools")}
+  EXA_API_KEY                - Exa web search
+  BRAVE_API_KEY              - Brave web search
+  PERPLEXITY_API_KEY         - Perplexity web search (API)
+  PERPLEXITY_COOKIES         - Perplexity web search (session cookie)
+  TAVILY_API_KEY             - Tavily web search
+  ANTHROPIC_SEARCH_API_KEY   - Anthropic search provider
+
+  ${chalk.dim("# Configuration")}
+  PI_CODING_AGENT_DIR        - Session storage directory (default: ~/${CONFIG_DIR_NAME}/agent)
+  PI_PACKAGE_DIR             - Override package directory (for Nix/Guix store paths)
+  PI_SMOL_MODEL              - Override smol/fast model (see --smol)
+  PI_SLOW_MODEL              - Override slow/reasoning model (see --slow)
+  PI_PLAN_MODEL              - Override planning model (see --plan)
+  PI_NO_PTY                  - Disable PTY-based interactive bash execution
+
+  For complete environment variable reference, see:
+  ${chalk.dim("docs/environment-variables.md")}
+${chalk.bold("Available Tools (default-enabled unless noted):")}
+  read          - Read file contents
+  bash          - Execute bash commands
+  edit          - Edit files with find/replace
+  write         - Write files (creates/overwrites)
+  grep          - Search file contents
+  find          - Find files by glob pattern
+  lsp           - Language server protocol (code intelligence)
+  python        - Execute Python code (requires: ${APP_NAME} setup python)
+  notebook      - Edit Jupyter notebooks
+  inspect_image - Analyze images with a vision model
+  browser       - Browser automation (Puppeteer)
+  task          - Launch sub-agents for parallel tasks
+  todo_write    - Manage todo/task lists
+  web_search    - Search the web
+  ask           - Ask user questions (interactive mode only)
+
+${chalk.bold("Plugin Options:")}
+  --plugin-dir <path>        Load plugin from directory (repeatable)
+
+${chalk.bold("Useful Commands:")}
+  xcsh agents unpack           - Export bundled subagents to ~/.xcsh/agent/agents (default)
+  xcsh agents unpack --project - Export bundled subagents to ./.xcsh/agents`;
+}
+
+export function printHelp(): void {
+	process.stdout.write(
+		`${chalk.bold(APP_NAME)} - AI coding assistant\n\n` +
+			`Run ${APP_NAME} --help for full command and option details.\n` +
+			`Run ${APP_NAME} <command> --help for command-specific help.\n\n` +
+			`${getExtraHelpText()}\n`,
+	);
+}

package/src/cli/classify-install-target.ts

@@ -0,0 +1,50 @@
+/**
+ * Classify an install spec as a marketplace plugin reference or a plain npm package.
+ *
+ * Rules (applied in order):
+ *  1. Starts with `@` (scoped npm) -> always npm.
+ *  2. Contains `@` after the first character -> split on the LAST `@`.
+ *     If the right-hand side is a known marketplace name, it's a marketplace ref.
+ *     Otherwise it's an npm spec (e.g. `pkg@1.2.3`).
+ *  3. No `@` -> npm.
+ */
+// Common npm dist-tags that should never be interpreted as marketplace names
+const NPM_DIST_TAGS = new Set([
+	"latest",
+	"next",
+	"beta",
+	"alpha",
+	"canary",
+	"rc",
+	"dev",
+	"stable",
+	"nightly",
+	"experimental",
+]);
+
+// Semver-like: starts with digit, or contains version range prefixes
+const LOOKS_LIKE_VERSION = /^[\d~^>=<]/;
+
+export function classifyInstallTarget(
+	spec: string,
+	knownMarketplaces: Set<string>,
+): { type: "marketplace"; name: string; marketplace: string } | { type: "npm"; spec: string } {
+	// Rule 1: scoped npm package — @ at position 0 is never a marketplace separator.
+	if (spec.startsWith("@")) return { type: "npm", spec };
+	// Rule 2: @ somewhere after the first character.
+	const atIdx = spec.lastIndexOf("@");
+	if (atIdx > 0) {
+		const rhs = spec.slice(atIdx + 1);
+		// Dist-tags and version specifiers are never marketplace names.
+		if (NPM_DIST_TAGS.has(rhs) || LOOKS_LIKE_VERSION.test(rhs)) {
+			return { type: "npm", spec };
+		}
+		if (knownMarketplaces.has(rhs)) {
+			return { type: "marketplace", name: spec.slice(0, atIdx), marketplace: rhs };
+		}
+		// Not a known marketplace — treat as npm version specifier.
+		return { type: "npm", spec };
+	}
+	// Rule 3: no @ at all.
+	return { type: "npm", spec };
+}

package/src/cli/commands/init-xdg.ts

@@ -0,0 +1,27 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+
+const APP_NAME = "xcsh";
+
+export async function initXdg(): Promise<void> {
+	if (process.platform !== "linux" && process.platform !== "darwin") {
+		console.error("XDG directory setup is only supported on Linux and macOS.");
+		process.exit(1);
+	}
+
+	const dataHome = process.env.XDG_DATA_HOME || path.join(os.homedir(), ".local/share");
+	const stateHome = process.env.XDG_STATE_HOME || path.join(os.homedir(), ".local/state");
+	const cacheHome = process.env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache");
+
+	const dirs = [path.join(dataHome, APP_NAME), path.join(stateHome, APP_NAME), path.join(cacheHome, APP_NAME)];
+
+	for (const dir of dirs) {
+		await fs.mkdir(dir, { recursive: true });
+		console.log(`Created ${dir.replace(os.homedir(), "~")}`);
+	}
+
+	console.log("\nXDG directories initialized.");
+	console.log("Ensure XDG_DATA_HOME, XDG_STATE_HOME, and XDG_CACHE_HOME");
+	console.log("are set in your shell profile for xcsh to use them.");
+}