@umsai/ums-code 0.0.11-post1

package/dist/src/services/McpPromptLoader.js

@@ -0,0 +1,192 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { getErrorMessage, getMCPServerPrompts, } from '@umsai/ums-code-core';
+import { CommandKind, } from '../ui/commands/types.js';
+/**
+ * Discovers and loads executable slash commands from prompts exposed by
+ * Model-Context-Protocol (MCP) servers.
+ */
+export class McpPromptLoader {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Loads all available prompts from all configured MCP servers and adapts
+     * them into executable SlashCommand objects.
+     *
+     * @param _signal An AbortSignal (unused for this synchronous loader).
+     * @returns A promise that resolves to an array of loaded SlashCommands.
+     */
+    loadCommands(_signal) {
+        const promptCommands = [];
+        if (!this.config) {
+            return Promise.resolve([]);
+        }
+        const mcpServers = this.config.getMcpServers() || {};
+        for (const serverName in mcpServers) {
+            const prompts = getMCPServerPrompts(this.config, serverName) || [];
+            for (const prompt of prompts) {
+                const commandName = `${prompt.name}`;
+                const newPromptCommand = {
+                    name: commandName,
+                    description: prompt.description || `Invoke prompt ${prompt.name}`,
+                    kind: CommandKind.MCP_PROMPT,
+                    subCommands: [
+                        {
+                            name: 'help',
+                            description: 'Show help for this prompt',
+                            kind: CommandKind.MCP_PROMPT,
+                            action: async () => {
+                                if (!prompt.arguments || prompt.arguments.length === 0) {
+                                    return {
+                                        type: 'message',
+                                        messageType: 'info',
+                                        content: `Prompt "${prompt.name}" has no arguments.`,
+                                    };
+                                }
+                                let helpMessage = `Arguments for "${prompt.name}":\n\n`;
+                                if (prompt.arguments && prompt.arguments.length > 0) {
+                                    helpMessage += `You can provide arguments by name (e.g., --argName="value") or by position.\n\n`;
+                                    helpMessage += `e.g., ${prompt.name} ${prompt.arguments?.map((_) => `"foo"`)} is equivalent to ${prompt.name} ${prompt.arguments?.map((arg) => `--${arg.name}="foo"`)}\n\n`;
+                                }
+                                for (const arg of prompt.arguments) {
+                                    helpMessage += `  --${arg.name}\n`;
+                                    if (arg.description) {
+                                        helpMessage += `    ${arg.description}\n`;
+                                    }
+                                    helpMessage += `    (required: ${arg.required ? 'yes' : 'no'})\n\n`;
+                                }
+                                return {
+                                    type: 'message',
+                                    messageType: 'info',
+                                    content: helpMessage,
+                                };
+                            },
+                        },
+                    ],
+                    action: async (context, args) => {
+                        if (!this.config) {
+                            return {
+                                type: 'message',
+                                messageType: 'error',
+                                content: 'Config not loaded.',
+                            };
+                        }
+                        const promptInputs = this.parseArgs(args, prompt.arguments);
+                        if (promptInputs instanceof Error) {
+                            return {
+                                type: 'message',
+                                messageType: 'error',
+                                content: promptInputs.message,
+                            };
+                        }
+                        try {
+                            const mcpServers = this.config.getMcpServers() || {};
+                            const mcpServerConfig = mcpServers[serverName];
+                            if (!mcpServerConfig) {
+                                return {
+                                    type: 'message',
+                                    messageType: 'error',
+                                    content: `MCP server config not found for '${serverName}'.`,
+                                };
+                            }
+                            const result = await prompt.invoke(promptInputs);
+                            if (result['error']) {
+                                return {
+                                    type: 'message',
+                                    messageType: 'error',
+                                    content: `Error invoking prompt: ${result['error']}`,
+                                };
+                            }
+                            if (!result.messages?.[0]?.content?.['text']) {
+                                return {
+                                    type: 'message',
+                                    messageType: 'error',
+                                    content: 'Received an empty or invalid prompt response from the server.',
+                                };
+                            }
+                            return {
+                                type: 'submit_prompt',
+                                content: JSON.stringify(result.messages[0].content.text),
+                            };
+                        }
+                        catch (error) {
+                            return {
+                                type: 'message',
+                                messageType: 'error',
+                                content: `Error: ${getErrorMessage(error)}`,
+                            };
+                        }
+                    },
+                    completion: async (_, partialArg) => {
+                        if (!prompt || !prompt.arguments) {
+                            return [];
+                        }
+                        const suggestions = [];
+                        const usedArgNames = new Set((partialArg.match(/--([^=]+)/g) || []).map((s) => s.substring(2)));
+                        for (const arg of prompt.arguments) {
+                            if (!usedArgNames.has(arg.name)) {
+                                suggestions.push(`--${arg.name}=""`);
+                            }
+                        }
+                        return suggestions;
+                    },
+                };
+                promptCommands.push(newPromptCommand);
+            }
+        }
+        return Promise.resolve(promptCommands);
+    }
+    parseArgs(userArgs, promptArgs) {
+        const argValues = {};
+        const promptInputs = {};
+        // arg parsing: --key="value" or --key=value
+        const namedArgRegex = /--([^=]+)=(?:"((?:\\.|[^"\\])*)"|([^ ]*))/g;
+        let match;
+        const remainingArgs = [];
+        let lastIndex = 0;
+        while ((match = namedArgRegex.exec(userArgs)) !== null) {
+            const key = match[1];
+            const value = match[2] ?? match[3]; // Quoted or unquoted value
+            argValues[key] = value;
+            // Capture text between matches as potential positional args
+            if (match.index > lastIndex) {
+                remainingArgs.push(userArgs.substring(lastIndex, match.index).trim());
+            }
+            lastIndex = namedArgRegex.lastIndex;
+        }
+        // Capture any remaining text after the last named arg
+        if (lastIndex < userArgs.length) {
+            remainingArgs.push(userArgs.substring(lastIndex).trim());
+        }
+        const positionalArgs = remainingArgs.join(' ').split(/ +/);
+        if (!promptArgs) {
+            return promptInputs;
+        }
+        for (const arg of promptArgs) {
+            if (argValues[arg.name]) {
+                promptInputs[arg.name] = argValues[arg.name];
+            }
+        }
+        const unfilledArgs = promptArgs.filter((arg) => arg.required && !promptInputs[arg.name]);
+        const missingArgs = [];
+        for (let i = 0; i < unfilledArgs.length; i++) {
+            if (positionalArgs.length > i && positionalArgs[i]) {
+                promptInputs[unfilledArgs[i].name] = positionalArgs[i];
+            }
+            else {
+                missingArgs.push(unfilledArgs[i].name);
+            }
+        }
+        if (missingArgs.length > 0) {
+            const missingArgNames = missingArgs.map((name) => `--${name}`).join(', ');
+            return new Error(`Missing required argument(s): ${missingArgNames}`);
+        }
+        return promptInputs;
+    }
+}
+//# sourceMappingURL=McpPromptLoader.js.map

package/dist/src/services/McpPromptLoader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"McpPromptLoader.js","sourceRoot":"","sources":["../../../src/services/McpPromptLoader.ts"],"names":[],"mappings":"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"}

package/dist/src/services/prompt-processors/argumentProcessor.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { IPromptProcessor } from './types.js';
+import { CommandContext } from '../../ui/commands/types.js';
+/**
+ * Appends the user's full command invocation to the prompt if arguments are
+ * provided, allowing the model to perform its own argument parsing.
+ *
+ * This processor is only used if the prompt does NOT contain {{args}}.
+ */
+export declare class DefaultArgumentProcessor implements IPromptProcessor {
+    process(prompt: string, context: CommandContext): Promise<string>;
+}

package/dist/src/services/prompt-processors/argumentProcessor.js

@@ -0,0 +1,20 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Appends the user's full command invocation to the prompt if arguments are
+ * provided, allowing the model to perform its own argument parsing.
+ *
+ * This processor is only used if the prompt does NOT contain {{args}}.
+ */
+export class DefaultArgumentProcessor {
+    async process(prompt, context) {
+        if (context.invocation.args) {
+            return `${prompt}\n\n${context.invocation.raw}`;
+        }
+        return prompt;
+    }
+}
+//# sourceMappingURL=argumentProcessor.js.map

package/dist/src/services/prompt-processors/argumentProcessor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"argumentProcessor.js","sourceRoot":"","sources":["../../../../src/services/prompt-processors/argumentProcessor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH;;;;;GAKG;AACH,MAAM,OAAO,wBAAwB;IACnC,KAAK,CAAC,OAAO,CAAC,MAAc,EAAE,OAAuB;QACnD,IAAI,OAAO,CAAC,UAAW,CAAC,IAAI,EAAE,CAAC;YAC7B,OAAO,GAAG,MAAM,OAAO,OAAO,CAAC,UAAW,CAAC,GAAG,EAAE,CAAC;QACnD,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;CACF"}

package/dist/src/services/prompt-processors/shellProcessor.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { CommandContext } from '../../ui/commands/types.js';
+import { IPromptProcessor } from './types.js';
+export declare class ConfirmationRequiredError extends Error {
+    commandsToConfirm: string[];
+    constructor(message: string, commandsToConfirm: string[]);
+}
+/**
+ * Handles prompt interpolation, including shell command execution (`!{...}`)
+ * and context-aware argument injection (`{{args}}`).
+ *
+ * This processor ensures that:
+ * 1. `{{args}}` outside `!{...}` are replaced with raw input.
+ * 2. `{{args}}` inside `!{...}` are replaced with shell-escaped input.
+ * 3. Shell commands are executed securely after argument substitution.
+ * 4. Parsing correctly handles nested braces.
+ */
+export declare class ShellProcessor implements IPromptProcessor {
+    private readonly commandName;
+    constructor(commandName: string);
+    process(prompt: string, context: CommandContext): Promise<string>;
+    /**
+     * Iteratively parses the prompt string to extract shell injections (!{...}),
+     * correctly handling nested braces within the command.
+     *
+     * @param prompt The prompt string to parse.
+     * @returns An array of extracted ShellInjection objects.
+     * @throws Error if an unclosed injection (`!{`) is found.
+     */
+    private extractInjections;
+}

package/dist/src/services/prompt-processors/shellProcessor.js

@@ -0,0 +1,162 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ApprovalMode, checkCommandPermissions, escapeShellArg, getShellConfiguration, ShellExecutionService, } from '@umsai/ums-code-core';
+import { SHELL_INJECTION_TRIGGER, SHORTHAND_ARGS_PLACEHOLDER, } from './types.js';
+export class ConfirmationRequiredError extends Error {
+    commandsToConfirm;
+    constructor(message, commandsToConfirm) {
+        super(message);
+        this.commandsToConfirm = commandsToConfirm;
+        this.name = 'ConfirmationRequiredError';
+    }
+}
+/**
+ * Handles prompt interpolation, including shell command execution (`!{...}`)
+ * and context-aware argument injection (`{{args}}`).
+ *
+ * This processor ensures that:
+ * 1. `{{args}}` outside `!{...}` are replaced with raw input.
+ * 2. `{{args}}` inside `!{...}` are replaced with shell-escaped input.
+ * 3. Shell commands are executed securely after argument substitution.
+ * 4. Parsing correctly handles nested braces.
+ */
+export class ShellProcessor {
+    commandName;
+    constructor(commandName) {
+        this.commandName = commandName;
+    }
+    async process(prompt, context) {
+        const userArgsRaw = context.invocation?.args || '';
+        if (!prompt.includes(SHELL_INJECTION_TRIGGER)) {
+            return prompt.replaceAll(SHORTHAND_ARGS_PLACEHOLDER, userArgsRaw);
+        }
+        const config = context.services.config;
+        if (!config) {
+            throw new Error(`Security configuration not loaded. Cannot verify shell command permissions for '${this.commandName}'. Aborting.`);
+        }
+        const { sessionShellAllowlist } = context.session;
+        const injections = this.extractInjections(prompt);
+        // If extractInjections found no closed blocks (and didn't throw), treat as raw.
+        if (injections.length === 0) {
+            return prompt.replaceAll(SHORTHAND_ARGS_PLACEHOLDER, userArgsRaw);
+        }
+        const { shell } = getShellConfiguration();
+        const userArgsEscaped = escapeShellArg(userArgsRaw, shell);
+        const resolvedInjections = injections.map((injection) => {
+            if (injection.command === '') {
+                return injection;
+            }
+            // Replace {{args}} inside the command string with the escaped version.
+            const resolvedCommand = injection.command.replaceAll(SHORTHAND_ARGS_PLACEHOLDER, userArgsEscaped);
+            return { ...injection, resolvedCommand };
+        });
+        const commandsToConfirm = new Set();
+        for (const injection of resolvedInjections) {
+            const command = injection.resolvedCommand;
+            if (!command)
+                continue;
+            // Security check on the final, escaped command string.
+            const { allAllowed, disallowedCommands, blockReason, isHardDenial } = checkCommandPermissions(command, config, sessionShellAllowlist);
+            if (!allAllowed) {
+                if (isHardDenial) {
+                    throw new Error(`${this.commandName} cannot be run. Blocked command: "${command}". Reason: ${blockReason || 'Blocked by configuration.'}`);
+                }
+                // If not a hard denial, respect YOLO mode and auto-approve.
+                if (config.getApprovalMode() !== ApprovalMode.YOLO) {
+                    disallowedCommands.forEach((uc) => commandsToConfirm.add(uc));
+                }
+            }
+        }
+        // Handle confirmation requirements.
+        if (commandsToConfirm.size > 0) {
+            throw new ConfirmationRequiredError('Shell command confirmation required', Array.from(commandsToConfirm));
+        }
+        let processedPrompt = '';
+        let lastIndex = 0;
+        for (const injection of resolvedInjections) {
+            // Append the text segment BEFORE the injection, substituting {{args}} with RAW input.
+            const segment = prompt.substring(lastIndex, injection.startIndex);
+            processedPrompt += segment.replaceAll(SHORTHAND_ARGS_PLACEHOLDER, userArgsRaw);
+            // Execute the resolved command (which already has ESCAPED input).
+            if (injection.resolvedCommand) {
+                const { result } = await ShellExecutionService.execute(injection.resolvedCommand, config.getTargetDir(), () => { }, new AbortController().signal, config.getShouldUseNodePtyShell());
+                const executionResult = await result;
+                // Handle Spawn Errors
+                if (executionResult.error && !executionResult.aborted) {
+                    throw new Error(`Failed to start shell command in '${this.commandName}': ${executionResult.error.message}. Command: ${injection.resolvedCommand}`);
+                }
+                // Append the output, making stderr explicit for the model.
+                processedPrompt += executionResult.output;
+                // Append a status message if the command did not succeed.
+                if (executionResult.aborted) {
+                    processedPrompt += `\n[Shell command '${injection.resolvedCommand}' aborted]`;
+                }
+                else if (executionResult.exitCode !== 0 &&
+                    executionResult.exitCode !== null) {
+                    processedPrompt += `\n[Shell command '${injection.resolvedCommand}' exited with code ${executionResult.exitCode}]`;
+                }
+                else if (executionResult.signal !== null) {
+                    processedPrompt += `\n[Shell command '${injection.resolvedCommand}' terminated by signal ${executionResult.signal}]`;
+                }
+            }
+            lastIndex = injection.endIndex;
+        }
+        // Append the remaining text AFTER the last injection, substituting {{args}} with RAW input.
+        const finalSegment = prompt.substring(lastIndex);
+        processedPrompt += finalSegment.replaceAll(SHORTHAND_ARGS_PLACEHOLDER, userArgsRaw);
+        return processedPrompt;
+    }
+    /**
+     * Iteratively parses the prompt string to extract shell injections (!{...}),
+     * correctly handling nested braces within the command.
+     *
+     * @param prompt The prompt string to parse.
+     * @returns An array of extracted ShellInjection objects.
+     * @throws Error if an unclosed injection (`!{`) is found.
+     */
+    extractInjections(prompt) {
+        const injections = [];
+        let index = 0;
+        while (index < prompt.length) {
+            const startIndex = prompt.indexOf(SHELL_INJECTION_TRIGGER, index);
+            if (startIndex === -1) {
+                break;
+            }
+            let currentIndex = startIndex + SHELL_INJECTION_TRIGGER.length;
+            let braceCount = 1;
+            let foundEnd = false;
+            while (currentIndex < prompt.length) {
+                const char = prompt[currentIndex];
+                // We count literal braces. This parser does not interpret shell quoting/escaping.
+                if (char === '{') {
+                    braceCount++;
+                }
+                else if (char === '}') {
+                    braceCount--;
+                    if (braceCount === 0) {
+                        const commandContent = prompt.substring(startIndex + SHELL_INJECTION_TRIGGER.length, currentIndex);
+                        const endIndex = currentIndex + 1;
+                        injections.push({
+                            command: commandContent.trim(),
+                            startIndex,
+                            endIndex,
+                        });
+                        index = endIndex;
+                        foundEnd = true;
+                        break;
+                    }
+                }
+                currentIndex++;
+            }
+            // Check if the inner loop finished without finding the closing brace.
+            if (!foundEnd) {
+                throw new Error(`Invalid syntax in command '${this.commandName}': Unclosed shell injection starting at index ${startIndex} ('!{'). Ensure braces are balanced.`);
+            }
+        }
+        return injections;
+    }
+}
+//# sourceMappingURL=shellProcessor.js.map

package/dist/src/services/prompt-processors/shellProcessor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shellProcessor.js","sourceRoot":"","sources":["../../../../src/services/prompt-processors/shellProcessor.ts"],"names":[],"mappings":"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"}

package/dist/src/services/prompt-processors/types.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { CommandContext } from '../../ui/commands/types.js';
+/**
+ * Defines the interface for a prompt processor, a module that can transform
+ * a prompt string before it is sent to the model. Processors are chained
+ * together to create a processing pipeline.
+ */
+export interface IPromptProcessor {
+    /**
+     * Processes a prompt string, applying a specific transformation as part of a pipeline.
+     *
+     * Each processor in a command's pipeline receives the output of the previous
+     * processor. This method provides the full command context, allowing for
+     * complex transformations that may require access to invocation details,
+     * application services, or UI state.
+     *
+     * @param prompt The current state of the prompt string. This may have been
+     *   modified by previous processors in the pipeline.
+     * @param context The full command context, providing access to invocation
+     *   details (like `context.invocation.raw` and `context.invocation.args`),
+     *   application services, and UI handlers.
+     * @returns A promise that resolves to the transformed prompt string, which
+     *   will be passed to the next processor or, if it's the last one, sent to the model.
+     */
+    process(prompt: string, context: CommandContext): Promise<string>;
+}
+/**
+ * The placeholder string for shorthand argument injection in custom commands.
+ * When used outside of !{...}, arguments are injected raw.
+ * When used inside !{...}, arguments are shell-escaped.
+ */
+export declare const SHORTHAND_ARGS_PLACEHOLDER = "{{args}}";
+/**
+ * The trigger string for shell command injection in custom commands.
+ */
+export declare const SHELL_INJECTION_TRIGGER = "!{";

package/dist/src/services/prompt-processors/types.js

@@ -0,0 +1,16 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * The placeholder string for shorthand argument injection in custom commands.
+ * When used outside of !{...}, arguments are injected raw.
+ * When used inside !{...}, arguments are shell-escaped.
+ */
+export const SHORTHAND_ARGS_PLACEHOLDER = '{{args}}';
+/**
+ * The trigger string for shell command injection in custom commands.
+ */
+export const SHELL_INJECTION_TRIGGER = '!{';
+//# sourceMappingURL=types.js.map

package/dist/src/services/prompt-processors/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/services/prompt-processors/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA6BH;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,UAAU,CAAC;AAErD;;GAEG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,IAAI,CAAC"}

package/dist/src/services/types.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { SlashCommand } from '../ui/commands/types.js';
+/**
+ * Defines the contract for any class that can load and provide slash commands.
+ * This allows the CommandService to be extended with new command sources
+ * (e.g., file-based, remote APIs) without modification.
+ *
+ * Loaders should receive any necessary dependencies (like Config) via their
+ * constructor.
+ */
+export interface ICommandLoader {
+    /**
+     * Discovers and returns a list of slash commands from the loader's source.
+     * @param signal An AbortSignal to allow cancellation.
+     * @returns A promise that resolves to an array of SlashCommand objects.
+     */
+    loadCommands(signal: AbortSignal): Promise<SlashCommand[]>;
+}

package/dist/src/services/types.js

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/services/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/services/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/src/test-utils/customMatchers.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+declare module 'vitest' {
+    interface Assertion<T> {
+        toHaveOnlyValidCharacters(): T;
+    }
+    interface AsymmetricMatchersContaining {
+        toHaveOnlyValidCharacters(): void;
+    }
+}
+export {};

package/dist/src/test-utils/customMatchers.js

@@ -0,0 +1,46 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/// <reference types="vitest/globals" />
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { expect } from 'vitest';
+// RegExp to detect invalid characters: backspace, and ANSI escape codes
+// eslint-disable-next-line no-control-regex
+const invalidCharsRegex = /[\b\x1b]/;
+function toHaveOnlyValidCharacters(buffer) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const { isNot } = this;
+    let pass = true;
+    const invalidLines = [];
+    for (let i = 0; i < buffer.lines.length; i++) {
+        const line = buffer.lines[i];
+        if (line.includes('\n')) {
+            pass = false;
+            invalidLines.push({ line: i, content: line });
+            break; // Fail fast on newlines
+        }
+        if (invalidCharsRegex.test(line)) {
+            pass = false;
+            invalidLines.push({ line: i, content: line });
+        }
+    }
+    return {
+        pass,
+        message: () => `Expected buffer ${isNot ? 'not ' : ''}to have only valid characters, but found invalid characters in lines:\n${invalidLines
+            .map((l) => `  [${l.line}]: "${l.content}"`) /* This line was changed */
+            .join('\n')}`,
+        actual: buffer.lines,
+        expected: 'Lines with no line breaks, backspaces, or escape codes.',
+    };
+}
+expect.extend({
+    toHaveOnlyValidCharacters,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+});
+//# sourceMappingURL=customMatchers.js.map

package/dist/src/test-utils/customMatchers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"customMatchers.js","sourceRoot":"","sources":["../../../src/test-utils/customMatchers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,wCAAwC;AAExC;;;;GAIG;AAEH,OAAO,EAAa,MAAM,EAAE,MAAM,QAAQ,CAAC;AAG3C,wEAAwE;AACxE,4CAA4C;AAC5C,MAAM,iBAAiB,GAAG,UAAU,CAAC;AAErC,SAAS,yBAAyB,CAAkB,MAAkB;IACpE,8DAA8D;IAC9D,MAAM,EAAE,KAAK,EAAE,GAAG,IAAW,CAAC;IAC9B,IAAI,IAAI,GAAG,IAAI,CAAC;IAChB,MAAM,YAAY,GAA6C,EAAE,CAAC;IAElE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7C,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAC7B,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACxB,IAAI,GAAG,KAAK,CAAC;YACb,YAAY,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;YAC9C,MAAM,CAAC,wBAAwB;QACjC,CAAC;QACD,IAAI,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACjC,IAAI,GAAG,KAAK,CAAC;YACb,YAAY,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;IAED,OAAO;QACL,IAAI;QACJ,OAAO,EAAE,GAAG,EAAE,CACZ,mBAAmB,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,0EAA0E,YAAY;aACzH,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,2BAA2B;aACvE,IAAI,CAAC,IAAI,CAAC,EAAE;QACjB,MAAM,EAAE,MAAM,CAAC,KAAK;QACpB,QAAQ,EAAE,yDAAyD;KACpE,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,CAAC;IACZ,yBAAyB;IACzB,8DAA8D;CACxD,CAAC,CAAC"}

package/dist/src/test-utils/mockCommandContext.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { CommandContext } from '../ui/commands/types.js';
+type DeepPartial<T> = T extends object ? {
+    [P in keyof T]?: DeepPartial<T[P]>;
+} : T;
+/**
+ * Creates a deep, fully-typed mock of the CommandContext for use in tests.
+ * All functions are pre-mocked with `vi.fn()`.
+ *
+ * @param overrides - A deep partial object to override any default mock values.
+ * @returns A complete, mocked CommandContext object.
+ */
+export declare const createMockCommandContext: (overrides?: DeepPartial<CommandContext>) => CommandContext;
+export {};