@f5-sales-demo/xcsh 19.95.4 → 19.97.0

package/src/cli/args.ts

@@ -6,6 +6,14 @@ import { APP_NAME, CONFIG_DIR_NAME, logger } from "@f5-sales-demo/pi-utils";
 import chalk from "chalk";
 import { parseEffort } from "../thinking";
 import { BUILTIN_TOOLS } from "../tools";
+import {
+	flagNameForChar,
+	flagSpec,
+	type LaunchFlagName,
+	normalizeFlagTokens,
+	takesValue,
+	type UnrecognizedFlag,
+} from "./flag-spec";
 
 export type Mode = "text" | "json" | "rpc" | "acp";
 
@@ -55,6 +63,169 @@ export interface Args {
 	fileArgs: string[];
 	/** Unknown flags (potentially extension flags) - map of flag name to value */
 	unknownFlags: Map<string, boolean | string>;
+	/**
+	 * Flags matched by neither the spec nor a known extension flag.
+	 *
+	 * Collected rather than reported here: the extension flag registry does not exist yet during the
+	 * first parse, so only `main.ts` can tell a genuine typo from a flag an extension will claim.
+	 */
+	unrecognizedFlags: UnrecognizedFlag[];
+}
+
+/**
+ * Apply one parsed flag to the result, keeping each flag's own value coercion.
+ *
+ * Split from the scanning loop so arity, aliasing and the `=` form are handled once, in one place,
+ * rather than repeated per flag as an `arg === "--x" && i + 1 < args.length` chain — which is how
+ * `--x=value` came to match nothing at all and vanish silently (#2469).
+ */
+const APPLY: Record<LaunchFlagName, (result: Args, value: string | true) => void> = {
+	model: (r, v) => {
+		r.model = v as string;
+	},
+	smol: (r, v) => {
+		r.smol = v as string;
+	},
+	slow: (r, v) => {
+		r.slow = v as string;
+	},
+	plan: (r, v) => {
+		r.plan = v as string;
+	},
+	provider: (r, v) => {
+		r.provider = v as string;
+	},
+	"api-key": (r, v) => {
+		r.apiKey = v as string;
+	},
+	"system-prompt": (r, v) => {
+		r.systemPrompt = v as string;
+	},
+	"append-system-prompt": (r, v) => {
+		r.appendSystemPrompt = v as string;
+	},
+	"allow-home": r => {
+		r.allowHome = true;
+	},
+	"no-sandbox": r => {
+		r.noSandbox = true;
+	},
+	"allow-path": (r, v) => {
+		r.allowPath = [...(r.allowPath ?? []), v as string];
+	},
+	mode: (r, v) => {
+		// Already validated against the spec's `options`.
+		r.mode = v as Mode;
+	},
+	print: r => {
+		r.print = true;
+	},
+	continue: r => {
+		r.continue = true;
+	},
+	resume: (r, v) => {
+		r.resume = v;
+	},
+	session: (r, v) => {
+		r.resume = v;
+	},
+	fork: (r, v) => {
+		r.fork = v as string;
+	},
+	"session-dir": (r, v) => {
+		r.sessionDir = v as string;
+	},
+	"no-session": r => {
+		r.noSession = true;
+	},
+	"provider-session-id": (r, v) => {
+		r.providerSessionId = v as string;
+	},
+	models: (r, v) => {
+		r.models = (v as string).split(",").map(s => s.trim());
+	},
+	"no-tools": r => {
+		r.noTools = true;
+	},
+	"no-mcp": r => {
+		r.noMcp = true;
+	},
+	"no-lsp": r => {
+		r.noLsp = true;
+	},
+	"no-pty": r => {
+		r.noPty = true;
+	},
+	tools: (r, v) => {
+		const toolNames = (v as string)
+			.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),
+				});
+			}
+		}
+		r.tools = validTools;
+	},
+	thinking: (r, v) => {
+		const thinking = parseEffort(v as string);
+		if (thinking !== undefined) {
+			r.thinking = thinking;
+		} else {
+			logger.warn("Invalid thinking level passed to --thinking", {
+				level: v,
+				validThinkingLevels: THINKING_EFFORTS,
+			});
+		}
+	},
+	hook: (r, v) => {
+		r.hooks = [...(r.hooks ?? []), v as string];
+	},
+	extension: (r, v) => {
+		r.extensions = [...(r.extensions ?? []), v as string];
+	},
+	"plugin-dir": (r, v) => {
+		r.pluginDirs = [...(r.pluginDirs ?? []), v as string];
+	},
+	"no-extensions": r => {
+		r.noExtensions = true;
+	},
+	"no-skills": r => {
+		r.noSkills = true;
+	},
+	skills: (r, v) => {
+		r.skills = (v as string).split(",").map(s => s.trim());
+	},
+	"no-rules": r => {
+		r.noRules = true;
+	},
+	export: (r, v) => {
+		r.export = v as string;
+	},
+	"list-models": (r, v) => {
+		r.listModels = v;
+	},
+	"no-title": r => {
+		r.noTitle = true;
+	},
+	help: r => {
+		r.help = true;
+	},
+	version: r => {
+		r.version = true;
+	},
+};
+
+/** True when the token could be an optional flag's value rather than the next flag or a file arg. */
+function isValueToken(token: string | undefined): token is string {
+	return token !== undefined && !token.startsWith("-") && !token.startsWith("@");
 }
 
 export function parseArgs(args: string[], extensionFlags?: Map<string, { type: "boolean" | "string" }>): Args {
@@ -62,146 +233,77 @@ export function parseArgs(args: string[], extensionFlags?: Map<string, { type: "
 		messages: [],
 		fileArgs: [],
 		unknownFlags: new Map(),
+		unrecognizedFlags: [],
 	};
 
-	for (let i = 0; i < args.length; i++) {
-		const arg = args[i];
+	const tokens = normalizeFlagTokens(args, extensionFlags);
 
-		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 === "--no-sandbox") {
-			result.noSandbox = true;
-		} else if (arg === "--allow-path" && i + 1 < args.length) {
-			result.allowPath = result.allowPath ?? [];
-			result.allowPath.push(args[++i]);
-		} 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;
+	for (let i = 0; i < tokens.length; i++) {
+		const token = tokens[i];
+
+		// Everything after `--` is content, not flags. Needed because an unrecognized flag is now a
+		// hard error, so there has to be a way to pass flag-looking text as a prompt.
+		if (token === "--") {
+			result.messages.push(...tokens.slice(i + 1));
+			break;
+		}
+
+		if (token.startsWith("@")) {
+			result.fileArgs.push(token.slice(1));
+			continue;
+		}
+
+		if (!token.startsWith("-") || token === "-") {
+			result.messages.push(token);
+			continue;
+		}
+
+		// An unknown `--name=value` survives normalization intact, so strip the value to get a name
+		// that can still be matched against the extension flag registry.
+		const name = token.startsWith("--") ? token.slice(2).split("=")[0] : flagNameForChar(token.slice(1));
+		const spec = name === undefined ? undefined : flagSpec(name);
+
+		if (spec && name !== undefined) {
+			if (!takesValue(spec)) {
+				APPLY[name as LaunchFlagName](result, true);
+				continue;
 			}
-		} 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 === "--no-mcp") {
-			result.noMcp = 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),
-					});
-				}
+			if (spec.arity === "optional-value") {
+				APPLY[name as LaunchFlagName](result, isValueToken(tokens[i + 1]) ? tokens[++i] : true);
+				continue;
 			}
-			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,
-				});
+			const value = tokens[i + 1];
+			if (value === undefined) {
+				result.unrecognizedFlags.push({ token, name });
+				continue;
 			}
-		} 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;
+			i++;
+			if (spec.options && !spec.options.includes(value)) {
+				logger.warn("Invalid value passed to flag", { flag: token, value, validValues: spec.options });
+				continue;
 			}
-		} 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]);
-				}
+			APPLY[name as LaunchFlagName](result, value);
+			continue;
+		}
+
+		// Extension flags are only known on the second parse, once extensions have loaded.
+		const extFlag = name === undefined ? undefined : extensionFlags?.get(name);
+		if (extFlag && name !== undefined) {
+			if (extFlag.type === "boolean") {
+				result.unknownFlags.set(name, true);
+			} else if (i + 1 < tokens.length) {
+				result.unknownFlags.set(name, tokens[++i]);
 			}
-			// Unknown flags without extensionFlags are silently ignored (first pass)
-		} else if (!arg.startsWith("-")) {
-			result.messages.push(arg);
+			continue;
 		}
+
+		// Record the flag, but do NOT consume the token after it. The bootstrap parse runs before
+		// extensions load, so it cannot know whether an unrecognized flag takes a value: swallowing
+		// the next token silently discards the user's prompt whenever the flag turns out to be
+		// boolean (`xcsh -p --verbose "do work"`). Leaving it means a string extension flag's value
+		// still reaches `messages`, which is the pre-existing behaviour and the lesser harm — the
+		// real fix is to load extensions before the first parse, which is out of scope here.
+		result.unrecognizedFlags.push({ token, name: name ?? token.replace(/^-+/, "") });
 	}
 
 	return result;

package/src/cli/flag-spec.ts

@@ -0,0 +1,219 @@
+/**
+ * The single source of truth for the root command's long flags.
+ *
+ * `xcsh --help` documented every long flag in the `=<value>` form while the parser matched only
+ * `--flag value`, so `xcsh --model=opus` silently ran the configured default and
+ * `xcsh --list-models=claude` fell through to the interactive TUI and hung (#2469). The two lived in
+ * separate tables — `commands/launch.ts` for help, `cli/args.ts` for parsing — and drifted.
+ *
+ * Both now derive from `LAUNCH_FLAGS`: `buildCliFlags` renders help from it, and `parseArgs` consumes
+ * it to resolve names and arity. Help and parser cannot disagree because they read the same datum.
+ *
+ * A leaf module on purpose — it imports only the thinking-effort list, so `commands/launch.ts` and
+ * `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";
+
+export type FlagArity = "boolean" | "value" | "optional-value" | "repeatable-value";
+
+export interface FlagSpec {
+	arity: FlagArity;
+	/** Single-character alias, as `-p` for `--print`. */
+	char?: string;
+	description: string;
+	/** Enumerated legal values, validated by the parser and rendered into help. */
+	options?: readonly string[];
+	/** Accepted by the parser but omitted from help — aliases and internal plumbing. */
+	hidden?: true;
+}
+
+/** Keeps the key names as literals (so `APPLY` must cover every one) while widening each value. */
+const defineFlags = <T extends Record<string, FlagSpec>>(flags: T): { [K in keyof T]: FlagSpec } => flags;
+
+/**
+ * Every long flag the root command accepts.
+ *
+ * Where the old tables disagreed, the parser's behavior won, since that is what users observed:
+ * `--resume` and `--list-models` take an optional value, and `--mode` accepts `acp`.
+ */
+export const LAUNCH_FLAGS = defineFlags({
+	model: {
+		arity: "value",
+		description: 'Model to use (fuzzy match: "opus", "gpt-5.2", or "p-openai/gpt-5.2")',
+	},
+	smol: { arity: "value", description: "Smol/fast model for lightweight tasks (or PI_SMOL_MODEL env)" },
+	slow: { arity: "value", description: "Slow/reasoning model for thorough analysis (or PI_SLOW_MODEL env)" },
+	plan: { arity: "value", description: "Plan model for architectural planning (or PI_PLAN_MODEL env)" },
+	provider: { arity: "value", description: "Provider to use (legacy; prefer --model)" },
+	"api-key": { arity: "value", description: "API key (defaults to env vars)" },
+	"system-prompt": { arity: "value", description: "System prompt (default: coding assistant prompt)" },
+	"append-system-prompt": { arity: "value", description: "Append text or file contents to the system prompt" },
+	"allow-home": { arity: "boolean", description: "Allow starting in ~ without auto-switching to a temp dir" },
+	"no-sandbox": {
+		arity: "boolean",
+		description: "Disable session filesystem isolation (allow access outside the CWD)",
+	},
+	"allow-path": {
+		arity: "repeatable-value",
+		description: "Grant read+write access to an extra directory (repeatable)",
+	},
+	mode: {
+		arity: "value",
+		description: "Output mode: text (default), json, rpc, or acp",
+		options: ["text", "json", "rpc", "acp"],
+	},
+	print: { arity: "boolean", char: "p", description: "Non-interactive mode: process prompt and exit" },
+	continue: { arity: "boolean", char: "c", description: "Continue previous session" },
+	resume: {
+		arity: "optional-value",
+		char: "r",
+		description: "Resume a session (by ID prefix, path, or picker if omitted)",
+	},
+	session: { arity: "optional-value", description: "Alias of --resume", hidden: true },
+	fork: { arity: "value", description: "Fork an existing session by ID prefix or path" },
+	"session-dir": { arity: "value", description: "Directory for session storage and lookup" },
+	"no-session": { arity: "boolean", description: "Don't save session (ephemeral)" },
+	"provider-session-id": { arity: "value", description: "Resume a provider-side session", hidden: true },
+	models: { arity: "value", description: "Comma-separated model patterns for Ctrl+P cycling" },
+	"no-tools": { arity: "boolean", description: "Disable all built-in tools" },
+	"no-mcp": { arity: "boolean", description: "Disable MCP server discovery and tools" },
+	"no-lsp": { arity: "boolean", description: "Disable LSP tools, formatting, and diagnostics" },
+	"no-pty": { arity: "boolean", description: "Disable PTY-based interactive bash execution" },
+	tools: { arity: "value", description: "Comma-separated list of tools to enable (default: all)" },
+	thinking: {
+		arity: "value",
+		description: `Set thinking level: ${THINKING_EFFORTS.join(", ")}`,
+		options: [...THINKING_EFFORTS],
+	},
+	hook: { arity: "repeatable-value", description: "Load a hook/extension file (can be used multiple times)" },
+	extension: {
+		arity: "repeatable-value",
+		char: "e",
+		description: "Load an extension file (can be used multiple times)",
+	},
+	"plugin-dir": { arity: "repeatable-value", description: "Load plugin from directory (repeatable)" },
+	"no-extensions": {
+		arity: "boolean",
+		description: "Disable extension discovery (explicit -e paths still work)",
+	},
+	"no-skills": { arity: "boolean", description: "Disable skills discovery and loading" },
+	skills: {
+		arity: "value",
+		description: "Comma-separated glob patterns to filter skills (e.g., git-*,docker)",
+	},
+	"no-rules": { arity: "boolean", description: "Disable rules discovery and loading" },
+	export: { arity: "value", description: "Export session file to HTML and exit" },
+	"list-models": { arity: "optional-value", description: "List available models (with optional fuzzy search)" },
+	"no-title": { arity: "boolean", description: "Disable title auto-generation" },
+	help: { arity: "boolean", char: "h", description: "Show help", hidden: true },
+	version: { arity: "boolean", char: "v", description: "Show version", hidden: true },
+});
+
+export type LaunchFlagName = keyof typeof LAUNCH_FLAGS;
+
+/** Long-flag name for a single-character alias, e.g. `p` -> `print`. */
+const CHAR_ALIASES: ReadonlyMap<string, LaunchFlagName> = new Map(
+	Object.entries(LAUNCH_FLAGS)
+		.filter((entry): entry is [LaunchFlagName, FlagSpec & { char: string }] => "char" in entry[1])
+		.map(([name, spec]) => [spec.char, name]),
+);
+
+export function flagSpec(name: string): FlagSpec | undefined {
+	return (LAUNCH_FLAGS as Record<string, FlagSpec>)[name];
+}
+
+export function flagNameForChar(char: string): LaunchFlagName | undefined {
+	return CHAR_ALIASES.get(char);
+}
+
+export function takesValue(spec: FlagSpec): boolean {
+	return spec.arity !== "boolean";
+}
+
+/** Render the help table from the spec, so the documented syntax is the accepted syntax. */
+export function buildCliFlags(): Record<string, FlagDescriptor> {
+	const flags: Record<string, FlagDescriptor> = {};
+	for (const [name, spec] of Object.entries(LAUNCH_FLAGS) as Array<[string, FlagSpec]>) {
+		if (spec.hidden) continue;
+		flags[name] =
+			spec.arity === "boolean"
+				? Flags.boolean({ char: spec.char, description: spec.description })
+				: Flags.string({
+						char: spec.char,
+						description: spec.description,
+						options: spec.options,
+						multiple: spec.arity === "repeatable-value",
+					});
+	}
+	return flags;
+}
+
+/** A `--name=value` token the parser could not attribute to any known flag. */
+export interface UnrecognizedFlag {
+	/** The token as written, including any `=value`, for the diagnostic. */
+	token: string;
+	/** The flag name without dashes or `=value`, for matching against extension flags. */
+	name: string;
+}
+
+export class FlagUsageError extends Error {}
+
+/**
+ * Rewrite `--name=value` into `["--name", "value"]` for every flag that takes a value.
+ *
+ * A boolean flag with `=` is an error rather than a guess: accepting `--no-sandbox=true` invites
+ * `--no-sandbox=false`, which the parser has no way to express, and quietly reading it as "on" would
+ * be exactly the class of bug #2469 reports. Unknown names are left intact so the unknown-flag path
+ * can report the token as the user wrote it.
+ *
+ * Short forms are untouched: no shell convention makes `-p=x` mean `-p x`.
+ */
+export function normalizeFlagTokens(
+	args: readonly string[],
+	extensionFlags?: ReadonlyMap<string, { type: "boolean" | "string" }>,
+): string[] {
+	const normalized: string[] = [];
+	let afterTerminator = false;
+
+	for (const arg of args) {
+		if (afterTerminator) {
+			normalized.push(arg);
+			continue;
+		}
+		if (arg === "--") {
+			afterTerminator = true;
+			normalized.push(arg);
+			continue;
+		}
+
+		const match = /^--([^=]+)=([\s\S]*)$/.exec(arg);
+		if (!match) {
+			normalized.push(arg);
+			continue;
+		}
+
+		const [, name, value] = match;
+		const spec = flagSpec(name);
+		if (spec) {
+			if (!takesValue(spec)) {
+				throw new FlagUsageError(`--${name} is a boolean flag and does not take a value`);
+			}
+			normalized.push(`--${name}`, value);
+			continue;
+		}
+
+		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`);
+			}
+			normalized.push(`--${name}`, value);
+			continue;
+		}
+
+		normalized.push(arg);
+	}
+
+	return normalized;
+}

package/src/cli/office-cli.ts

@@ -222,11 +222,25 @@ async function runSideload(app: OfficeApp): Promise<void> {
 	}
 }
 
+/**
+ * The two long-running halves of the command, injectable so the dispatch order can be
+ * tested without binding :8444 or shelling out to `office-addin-debugging`.
+ */
+export interface OfficeCommandDeps {
+	sideload: (app: OfficeApp) => Promise<void>;
+	serve: () => Promise<void>;
+}
+
+const defaultCommandDeps: OfficeCommandDeps = { sideload: runSideload, serve: runServe };
+
 /** Dispatch an `xcsh office <action>` invocation. */
-export async function runOfficeCommand(args: OfficeCommandArgs): Promise<void> {
+export async function runOfficeCommand(
+	args: OfficeCommandArgs,
+	deps: OfficeCommandDeps = defaultCommandDeps,
+): Promise<void> {
 	switch (args.action) {
 		case "serve":
-			await runServe();
+			await deps.serve();
 			return;
 		case "manifest": {
 			const text = await writeManifest(args.out);
@@ -238,7 +252,16 @@ export async function runOfficeCommand(args: OfficeCommandArgs): Promise<void> {
 			return;
 		}
 		case "sideload":
-			await runSideload(args.app ?? "excel");
+			// Register FIRST, then serve — serve blocks until a signal, so anything
+			// sequenced after it would never run.
+			//
+			// Registering alone used to be the whole command, which quietly left the
+			// operator half-configured: the pane's cwd (what its file tools and shell are
+			// confined to) comes from wherever `office serve` was launched, so a bare
+			// sideload produced a pane pointed at some unrelated folder, or at nothing.
+			// One command from the folder you care about now does both.
+			await deps.sideload(args.app ?? "excel");
+			await deps.serve();
 			return;
 		case "recycle":
 			console.log(await recycleOfficeServe());