monacopilot 0.11.5 → 0.11.7

package/README.md

@@ -33,7 +33,7 @@
 - [Completion Request Options](#completion-request-options)
   - [Custom Headers for AI Model Requests](#custom-headers-for-ai-model-requests)
 - [Using a Different Language for the API Handler](#using-a-different-language-for-the-api-handler)
-- [Select and Edit](#select-and-edit)
+- [Select and Modify](#select-and-modify)
 - [Contributing](#contributing)
 
 ### Examples
@@ -142,7 +142,8 @@ registerCompletion(monaco, editor, {
 });
 ```
 
-The `registerCompletion` function returns a `completion` object with useful methods such as `trigger` and `dispose`. The `trigger` method is explained later in this document. The `dispose` method should be used to clean up resources when the completion object is no longer needed. For instance, in a React component, you can call `completion.dispose()` within the `useEffect` cleanup function to ensure proper disposal when the component unmounts.
+> **Note:** The `registerCompletion` function returns a `completion` object with a `deregister` method. This method should be used to clean up the completion functionality when it's no longer needed.
+> For example, in a React component, you can call `completion.deregister()` within the `useEffect` cleanup function to ensure proper disposal when the component unmounts.
 
 🎉 Congratulations! The AI auto-completion is now connected to the Monaco Editor. Start typing and see completions in the editor.
 
@@ -509,7 +510,7 @@ copilot.complete({
 
 #### Parameters
 
-The `customPrompt` function receives a `completionMetadata` object, which contains information about the current editor state and can be used to tailor the prompt.
+The `customPrompt` function receives a `metadata` object, which contains information about the current editor state and can be used to tailor the prompt.
 
 ##### Completion Metadata
 
@@ -532,7 +533,7 @@ The `editorState.completionMode` can be one of the following:
 | `complete` | Indicates that there is a character after the cursor but not immediately. In this mode, the AI will generate content to complete the text from the cursor position. |
 | `continue` | Indicates that there is no character after the cursor. In this mode, the AI will generate content to continue the text from the cursor position.                    |
 
-For additional `completionMetadata` needs, please [open an issue](https://github.com/arshad-yaseen/monacopilot/issues/new).
+For additional `metadata` needs, please [open an issue](https://github.com/arshad-yaseen/monacopilot/issues/new).
 
 The `customPrompt` function should return an object with two properties:
 
@@ -599,7 +600,7 @@ Check out the [prompt.ts](https://github.com/arshad-yaseen/monacopilot/blob/main
 
 ### Metadata Overview
 
-The request body's `completionMetadata` object contains essential information for crafting a prompt for the AI model to generate accurate completions. See the [Completion Metadata](#completion-metadata) section for more details.
+The request body's `metadata` object contains essential information for crafting a prompt for the AI model to generate accurate completions. See the [Completion Metadata](#completion-metadata) section for more details.
 
 ### Example Implementation (Python with FastAPI)
 
@@ -614,7 +615,7 @@ app = FastAPI()
 async def handle_completion(request: Request):
     try:
         body = await request.json()
-        metadata = body['completionMetadata']
+        metadata = body['metadata']
 
         prompt = f"""Please complete the following {metadata['language']} code:
 
@@ -648,9 +649,9 @@ registerCompletion(monaco, editor, {
 });
 ```
 
-## Select and Edit
+## Select and Modify
 
-Select and Edit is a feature that allows you to select code from the editor and edit it inline with AI assistance.
+This feature allows you to edit the code by selecting the part you want to modify and ask AI to modify it.
 
 This feature is coming soon™️.
 

package/build/index.d.mts

@@ -1,6 +1,63 @@
 import * as monaco from 'monaco-editor/esm/vs/editor/editor.api';
 import * as monaco_editor from 'monaco-editor';
 
+type CurrentFileName = string;
+type Technologies = string[];
+type RelatedFile = {
+    /**
+     * The relative path from the current editing code in the editor to an external file.
+     *
+     * Examples:
+     * - To include a file `utils.js` in the same directory, set as `./utils.js`.
+     * - To include a file `utils.js` in the parent directory, set as `../utils.js`.
+     * - To include a file `utils.js` in the child directory, set as `./child/utils.js`.
+     */
+    path: string;
+    /**
+     * The content of the external file as a string.
+     */
+    content: string;
+};
+type Context = {
+    /**
+     * The programming language of the current file being edited.
+     */
+    currentLanguage: string;
+    /**
+     * The resolved programming language of the current file being edited.
+     * This is used to provide more specific language-based completions and suggestions,
+     * especially when the initial language might be ambiguous (e.g., 'javascript' could be resolved to 'JavaScript (ES2024)').
+     */
+    resolvedCurrentLanguage: string;
+    /**
+     * The name of the file you are currently editing.
+     */
+    currentFileName?: CurrentFileName;
+    /**
+     * The related files with the adjusted maximum lines.
+     */
+    relatedFiles?: RelatedFile[];
+    /**
+     * The technologies (libraries, frameworks, etc.) you want to use for the completion.
+     * This can provide technology-specific completions.
+     * If you don't specify a technology, the completion will be specific to the language (provided as the `language`).
+     *
+     * @example
+     * ['react', 'nextjs', 'tailwindcss', 'tanstack/react-query']
+     * ['tensorflow', 'keras', 'numpy', 'pandas']
+     * etc.
+     */
+    technologies?: Technologies;
+    /**
+     * The maximum number of lines of code to include in the context sent to the Language Model (LLM).
+     * This helps to reduce the cost of the completion request.
+     *
+     * @default undefined - No limit is applied if not specified
+     */
+    maxContextLines?: number;
+};
+type BuildContextOptions = Omit<Context, 'resolvedCurrentLanguage'>;
+
 type OpenAIModel = 'gpt-4o' | 'gpt-4o-mini' | 'o1-preview' | 'o1-mini';
 type GroqModel = 'llama-3-70b';
 type AnthropicModel = 'claude-3.5-sonnet' | 'claude-3-opus' | 'claude-3-haiku' | 'claude-3-sonnet';
@@ -83,38 +140,26 @@ type CustomCopilotModelTransformResponse = (response: unknown) => {
      */
     completion: string | null;
 };
+type CustomPrompt<T> = (metadata: T) => Partial<PromptData>;
 
 type Monaco = typeof monaco;
 type StandaloneCodeEditor = monaco.editor.IStandaloneCodeEditor;
 type CursorPosition = monaco.IPosition;
+type EditorSelection = monaco.Selection;
 
 type Endpoint = string;
-type Filename = string;
-type Technologies = string[];
-type RelatedFile = {
-    /**
-     * The relative path from the current editing code in the editor to an external file.
-     *
-     * Examples:
-     * - To include a file `utils.js` in the same directory, set as `./utils.js`.
-     * - To include a file `utils.js` in the parent directory, set as `../utils.js`.
-     * - To include a file `utils.js` in the child directory, set as `./child/utils.js`.
-     */
-    path: string;
-    /**
-     * The content of the external file as a string.
-     */
-    content: string;
-};
 interface RegisterCompletionOptions {
     /**
-     * Language of the current model
+     * The API endpoint to fetch the completion item from.
      */
-    language: string;
+    endpoint: Endpoint;
     /**
-     * The API endpoint where you started the completion service.
+     * The context object containing contextual information for generating relevant completions.
+  
+     * This object is created by the `buildContext` function from monacopilot.
+     * It helps tailor completions to the specific project environment and coding context.
      */
-    endpoint: Endpoint;
+    context: Context;
     /**
      * Specifies when the completion service should provide code completions.
      *
@@ -128,36 +173,6 @@ interface RegisterCompletionOptions {
      * @default 'onIdle'
      */
     trigger?: 'onTyping' | 'onIdle' | 'onDemand';
-    /**
-     * The name of the file you are editing. This is used to provide more relevant completions based on the file's purpose.
-     * For example, if you are editing a file named `utils.js`, the completions will be more relevant to utility functions.
-     */
-    filename?: Filename;
-    /**
-     * The technologies (libraries, frameworks, etc.) you want to use for the completion.
-     * This can provide technology-specific completions.
-     * If you don't specify a technology, the completion will be specific to the language (provided as the `language`).
-     *
-     * @example
-     * ['react', 'nextjs', 'tailwindcss', 'tanstack/react-query']
-     * ['tensorflow', 'keras', 'numpy', 'pandas']
-     * etc.
-     */
-    technologies?: Technologies;
-    /**
-     * Helps to give more relevant completions based on the full context.
-     * You can include things like the contents/codes of other files in the same workspace.
-     */
-    relatedFiles?: RelatedFile[];
-    /**
-     * The maximum number of lines of code to include in the completion request.
-     * This limits the request size to the model to prevent `429 Too Many Requests` errors
-     * and reduce costs for long code.
-     *
-     * It is recommended to set `maxContextLines` to `60` or less if you are using `Groq` as your provider,
-     * since `Groq` does not implement pay-as-you-go pricing and has only low rate limits.
-     */
-    maxContextLines?: number;
     /**
      * Callback function that is called when an error occurs during the completion request.
      * This function allows you to handle errors gracefully and provide appropriate feedback to the user.
@@ -188,23 +203,23 @@ interface CompletionRegistration {
      */
     deregister: () => void;
 }
-interface CompletionRequest {
+interface CompletionApiRequest {
     /**
      * The body of the completion request.
      */
-    body: CompletionRequestBody;
+    body: CompletionApiRequestBody;
     /**
      * Additional options to include in the completion request.
      */
-    options?: CompletionRequestOptions;
+    options?: CompletionApiRequestOptions;
 }
-interface CompletionRequestBody {
+interface CompletionApiRequestBody {
     /**
      * The metadata required to generate the completion.
      */
-    completionMetadata: CompletionMetadata;
+    metadata: CompletionMetadata;
 }
-interface CompletionRequestOptions {
+interface CompletionApiRequestOptions {
     /**
      * Custom headers to include in the request to the AI provider.
      */
@@ -214,34 +229,21 @@ interface CompletionRequestOptions {
      * This function allows you to override the default system and user prompts
      * used in the completion request, providing more control over the AI's context and behavior.
      *
-     * @param completionMetadata - Metadata about the current completion context
+     * @param metadata - Metadata about the current completion context
      * @returns An object containing custom 'system' and 'user' prompts
      */
-    customPrompt?: CustomPrompt;
+    customPrompt?: CustomPrompt<CompletionMetadata>;
 }
-type CustomPrompt = (completionMetadata: CompletionMetadata) => Partial<PromptData>;
-interface CompletionResponse {
+interface CompletionApiResponse {
     completion: string | null;
     error?: string;
 }
 type CompletionMode = 'insert' | 'complete' | 'continue';
 interface CompletionMetadata {
     /**
-     * The programming language of the code.
-     */
-    language: string | undefined;
-    /**
-     * The name of the file being edited.
-     */
-    filename: Filename | undefined;
-    /**
-     * The technologies used in the completion.
-     */
-    technologies: Technologies | undefined;
-    /**
-     * Additional context from related files.
+     * The context object containing contextual information for generating relevant completions.
      */
-    relatedFiles: RelatedFile[] | undefined;
+    context?: Context;
     /**
      * The text that appears after the cursor.
      */
@@ -258,11 +260,6 @@ interface CompletionMetadata {
      * The current state of the editor.
      */
     editorState: {
-        /**
-         * The mode of the completion.
-         * - `fill-in-the-middle`: Indicates that the cursor is positioned within the existing text. In this mode, the AI will generate content to be inserted at the cursor position.
-         * - `completion`: Indicates that the cursor is at the end of the existing text. In this mode, the AI will generate content to continue or complete the text from the cursor position.
-         */
         completionMode: CompletionMode;
     };
 }
@@ -272,7 +269,114 @@ type FetchCompletionItemReturn = {
 };
 interface FetchCompletionItemParams {
     endpoint: string;
-    body: CompletionRequestBody;
+    body: CompletionApiRequestBody;
+}
+
+interface SelectionActionsRegistration {
+    deregister: () => void;
+}
+type SelectionAction = 'modify';
+interface RegisterSelectionActionsOptions {
+    actions: SelectionAction[];
+    modify: ModifyOptions;
+    onError?: (error: Error) => void;
+}
+interface ModifyOptions {
+    /**
+     * The API endpoint to fetch the modified text from.
+     */
+    endpoint: string;
+    /**
+     * The context object containing contextual information for generating relevant modifications.
+     */
+    context: Context;
+    /**
+     * The text to display as a placeholder in the text area where users input their modification instructions.
+     */
+    placeholder?: string;
+    /**
+     * Custom fetch modified text handler. This function overrides the default modified text fetch handler.
+     * It allows you to customize how modified text requests are made and responses are processed.
+     * You can implement your own logic for fetching and processing modified text.
+     * The function should return either a string (the modified text to be replaced with the selected text) or null.
+     * @param params - The parameters for the modified text request.
+     * @param {string} params.endpoint - The endpoint to fetch the modified text from.
+     * @param {ModifyApiRequestBody} params.body - The body of the modified text request.
+     * @returns {Promise<{modifiedText: string | null}>} An object containing the modified text or null if no modified text is available.
+     */
+    requestHandler?: FetchModifiedTextHandler;
+}
+interface ModifyMetadata {
+    /**
+     * The context object containing contextual information for generating relevant modifications.
+     */
+    context?: Context;
+    /**
+     * The full text of the current file.
+     */
+    fullText: string;
+    /**
+     * The selected text range in the file.
+     */
+    selection: EditorSelection | null;
+    /**
+     * The selected text.
+     * This will be null if the user has a cursor position and no text is selected.
+     */
+    selectedText: string | null;
+    /**
+     * The current cursor position.
+     */
+    cursorPosition: CursorPosition | null;
+    /**
+     * The text before the cursor position.
+     * This will be null if the user has selected text instead of having a cursor position.
+     */
+    textBeforeCursor: string | null;
+    /**
+     * The text after the cursor position.
+     * This will be null if the user has selected text instead of having a cursor position.
+     */
+    textAfterCursor: string | null;
+    /**
+     * The user-provided instructions for modifying the selected text.
+     */
+    prompt: string;
+}
+interface FetchModifiedTextParams {
+    endpoint: string;
+    body: ModifyApiRequestBody;
+}
+interface FetchModifiedTextReturn {
+    modifiedText: string | null;
+}
+type FetchModifiedTextHandler = (params: FetchModifiedTextParams) => Promise<FetchModifiedTextReturn>;
+interface ModifyApiRequest {
+    body: ModifyApiRequestBody;
+    options?: ModifyApiRequestOptions;
+}
+interface ModifyApiRequestOptions {
+    /**
+     * Custom headers to include in the request to the AI provider.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Custom prompt generator function for the modify request.
+     * This function allows you to override the default system and user prompts
+     * used in the modify request, providing more control over the AI's context and behavior.
+     *
+     * @param metadata - Metadata about the current modify context
+     * @returns An object containing custom 'system' and 'user' prompts
+     */
+    customPrompt?: ModifyCustomPrompt;
+}
+type ModifyCustomPrompt = (metadata: ModifyMetadata) => Partial<PromptData>;
+interface ModifyApiRequestBody {
+    metadata: ModifyMetadata;
+}
+interface ModifyApiResponse {
+    modifiedText: string | null;
+    error?: string;
 }
 
 declare class Copilot {
@@ -281,12 +385,16 @@ declare class Copilot {
     private model;
     constructor(apiKey: string, options?: CopilotOptions);
     private validateInputs;
-    complete(request: CompletionRequest): Promise<CompletionResponse>;
+    complete(request: CompletionApiRequest): Promise<CompletionApiResponse>;
+    modify(request: ModifyApiRequest): Promise<ModifyApiResponse>;
+    private makeApiCall;
     private generatePrompt;
     private prepareRequestDetails;
     private sendCompletionRequest;
     private processCompletionResponse;
+    private processModifyResponse;
     private handleCompletionError;
+    private handleModifyError;
 }
 
 /**
@@ -302,4 +410,21 @@ declare const registerCompletion: (monaco: Monaco, editor: StandaloneCodeEditor,
  */
 declare const registerCopilot: (monaco: typeof monaco_editor, editor: monaco_editor.editor.IStandaloneCodeEditor, options: RegisterCompletionOptions) => CompletionRegistration;
 
-export { type CompletionMetadata, type CompletionRegistration, type CompletionRequest, type CompletionRequestBody, type CompletionRequestOptions, Copilot, type CopilotModel, type CopilotOptions, type CopilotProvider, type CustomCopilotModel, type CustomCopilotModelConfig, type CustomCopilotModelTransformResponse, type Monaco, type RegisterCompletionOptions, type StandaloneCodeEditor, registerCompletion, registerCopilot };
+/**
+ * Registers the selection action functionality with the Monaco editor.
+ *
+ * @param monaco - The Monaco instance.
+ * @param editor - The editor instance.
+ * @param options - Options for the action functionality.
+ * @returns A SelectionActionsRegistration object with a deregister method.
+ */
+declare const registerSelectionActions: (monaco: Monaco, editor: StandaloneCodeEditor, options: RegisterSelectionActionsOptions) => SelectionActionsRegistration;
+
+/**
+ * Builds a context object containing contextual information for generating relevant completions/suggestions.
+ * @param options - The options for building the context.
+ * @returns The context object.
+ */
+declare const buildContext: (options: BuildContextOptions) => Context;
+
+export { type CompletionApiRequest, type CompletionApiRequestBody, type CompletionApiRequestOptions, type CompletionMetadata, type CompletionRegistration, type Context, Copilot, type CopilotModel, type CopilotOptions, type CopilotProvider, type CustomCopilotModel, type CustomCopilotModelConfig, type CustomCopilotModelTransformResponse, type Monaco, type RegisterCompletionOptions, type StandaloneCodeEditor, buildContext, registerCompletion, registerCopilot, registerSelectionActions };