cecli-dev 0.93.1__py3-none-any.whl

cecli/onboarding.py

@@ -0,0 +1,301 @@
+import http.server
+import os
+import socketserver
+import threading
+import time
+import webbrowser
+from urllib.parse import parse_qs, urlparse
+
+import requests
+
+from cecli import urls
+from cecli.io import InputOutput
+from cecli.mcp.oauth import find_available_port, generate_pkce_codes
+
+
+def check_openrouter_tier(api_key):
+    """
+    Checks if the user is on a free tier for OpenRouter.
+
+    Args:
+        api_key: The OpenRouter API key to check.
+
+    Returns:
+        A boolean indicating if the user is on a free tier (True) or paid tier (False).
+        Returns True if the check fails.
+    """
+    try:
+        response = requests.get(
+            "https://openrouter.ai/api/v1/auth/key",
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=5,
+        )
+        response.raise_for_status()
+        data = response.json()
+        return data.get("data", {}).get("is_free_tier", True)
+    except Exception:
+        return True
+
+
+def try_to_select_default_model():
+    """
+    Attempts to select a default model based on available API keys.
+    Checks OpenRouter tier status to select appropriate model.
+
+    Returns:
+        The name of the selected model, or None if no suitable default is found.
+    """
+    openrouter_key = os.environ.get("OPENROUTER_API_KEY")
+    if openrouter_key:
+        is_free_tier = check_openrouter_tier(openrouter_key)
+        if is_free_tier:
+            return "openrouter/deepseek/deepseek-r1:free"
+        else:
+            return "openrouter/anthropic/claude-sonnet-4"
+    model_key_pairs = [
+        ("ANTHROPIC_API_KEY", "sonnet"),
+        ("DEEPSEEK_API_KEY", "deepseek"),
+        ("OPENAI_API_KEY", "gpt-4o"),
+        ("GEMINI_API_KEY", "gemini/gemini-2.5-pro-exp-03-25"),
+        ("VERTEXAI_PROJECT", "vertex_ai/gemini-2.5-pro-exp-03-25"),
+    ]
+    for env_key, model_name in model_key_pairs:
+        api_key_value = os.environ.get(env_key)
+        if api_key_value:
+            return model_name
+    return None
+
+
+async def offer_openrouter_oauth(io):
+    """
+    Offers OpenRouter OAuth flow to the user if no API keys are found.
+
+    Args:
+        io: The InputOutput object for user interaction.
+
+    Returns:
+        True if authentication was successful, False otherwise.
+    """
+    io.tool_output("OpenRouter provides free and paid access to many LLMs.")
+    if await io.confirm_ask(
+        "Login to OpenRouter or create a free account?", default="y", acknowledge=True
+    ):
+        openrouter_key = start_openrouter_oauth_flow(io)
+        if openrouter_key:
+            os.environ["OPENROUTER_API_KEY"] = openrouter_key
+            return True
+        io.tool_error("OpenRouter authentication did not complete successfully.")
+    return False
+
+
+async def select_default_model(args, io):
+    """
+    Selects a default model based on available API keys if no model is specified.
+    Offers OAuth flow for OpenRouter if no keys are found.
+
+    Args:
+        args: The command line arguments object.
+        io: The InputOutput object for user interaction.
+
+    Returns:
+        The name of the selected model, or None if no suitable default is found.
+    """
+    if args.model:
+        return args.model
+    model = try_to_select_default_model()
+    if model:
+        io.tool_warning(f"Using {model} model with API key from environment.")
+        return model
+    no_model_msg = "No LLM model was specified and no API keys were provided."
+    io.tool_warning(no_model_msg)
+    await offer_openrouter_oauth(io)
+    model = try_to_select_default_model()
+    if model:
+        return model
+    await io.offer_url(urls.models_and_keys, "Open documentation URL for more info?")
+
+
+# Function to exchange the authorization code for an API key
+def exchange_code_for_key(code, code_verifier, io):
+    try:
+        response = requests.post(
+            "https://openrouter.ai/api/v1/auth/keys",
+            headers={"Content-Type": "application/json"},
+            json={"code": code, "code_verifier": code_verifier, "code_challenge_method": "S256"},
+            timeout=30,
+        )
+        response.raise_for_status()
+        data = response.json()
+        api_key = data.get("key")
+        if not api_key:
+            io.tool_error("Error: 'key' not found in OpenRouter response.")
+            io.tool_error(f"Response: {response.text}")
+            return None
+        return api_key
+    except requests.exceptions.Timeout:
+        io.tool_error("Error: Request to OpenRouter timed out during code exchange.")
+        return None
+    except requests.exceptions.HTTPError as e:
+        io.tool_error(
+            "Error exchanging code for OpenRouter key:"
+            f" {e.response.status_code} {e.response.reason}"
+        )
+        io.tool_error(f"Response: {e.response.text}")
+        return None
+    except requests.exceptions.RequestException as e:
+        io.tool_error(f"Error exchanging code for OpenRouter key: {e}")
+        return None
+    except Exception as e:
+        io.tool_error(f"Unexpected error during code exchange: {e}")
+        return None
+
+
+def start_openrouter_oauth_flow(io):
+    """Initiates the OpenRouter OAuth PKCE flow using a local server."""
+    port = find_available_port()
+    if not port:
+        io.tool_error("Could not find an available port between 8484 and 8584.")
+        io.tool_error("Please ensure a port in this range is free, or configure manually.")
+        return None
+    callback_url = f"http://localhost:{port}/callback/cecli"
+    auth_code = None
+    server_error = None
+    server_started = threading.Event()
+    shutdown_server = threading.Event()
+
+    class OAuthCallbackHandler(http.server.SimpleHTTPRequestHandler):
+        def do_GET(self):
+            nonlocal auth_code, server_error
+            parsed_path = urlparse(self.path)
+            if parsed_path.path == "/callback/cecli":
+                query_params = parse_qs(parsed_path.query)
+                if "code" in query_params:
+                    auth_code = query_params["code"][0]
+                    self.send_response(200)
+                    self.send_header("Content-type", "text/html")
+                    self.end_headers()
+                    self.wfile.write(
+                        b"<html><body><h1>Success!</h1><p>cecli has received the authentication"
+                        b" code. You can close this browser tab.</p></body></html>"
+                    )
+                    shutdown_server.set()
+                else:
+                    self.send_response(302)
+                    self.send_header("Location", urls.website)
+                    self.end_headers()
+            else:
+                self.send_response(302)
+                self.send_header("Location", urls.website)
+                self.end_headers()
+                self.wfile.write(b"Not Found")
+
+        def log_message(self, format, *args):
+            pass
+
+    def run_server():
+        nonlocal server_error
+        try:
+            with socketserver.TCPServer(("localhost", port), OAuthCallbackHandler) as httpd:
+                io.tool_output(f"Temporary server listening on {callback_url}", log_only=True)
+                server_started.set()
+                while not shutdown_server.is_set():
+                    httpd.handle_request()
+                    time.sleep(0.1)
+                io.tool_output("Shutting down temporary server.", log_only=True)
+        except Exception as e:
+            server_error = f"Failed to start or run temporary server: {e}"
+            server_started.set()
+            shutdown_server.set()
+
+    server_thread = threading.Thread(target=run_server, daemon=True)
+    server_thread.start()
+    if not server_started.wait(timeout=5):
+        io.tool_error("Temporary authentication server failed to start in time.")
+        shutdown_server.set()
+        server_thread.join(timeout=1)
+        return None
+    if server_error:
+        io.tool_error(server_error)
+        shutdown_server.set()
+        server_thread.join(timeout=1)
+        return None
+    code_verifier, code_challenge = generate_pkce_codes()
+    auth_url_base = "https://openrouter.ai/auth"
+    auth_params = {
+        "callback_url": callback_url,
+        "code_challenge": code_challenge,
+        "code_challenge_method": "S256",
+    }
+    auth_url = f"{auth_url_base}?{'&'.join(f'{k}={v}' for k, v in auth_params.items())}"
+    io.tool_output("\nPlease open this URL in your browser to connect cecli with OpenRouter:")
+    io.tool_output()
+    print(auth_url)
+    MINUTES = 5
+    io.tool_output(f"\nWaiting up to {MINUTES} minutes for you to finish in the browser...")
+    io.tool_output("Use Control-C to interrupt.")
+    try:
+        webbrowser.open(auth_url)
+    except Exception:
+        pass
+    interrupted = False
+    try:
+        shutdown_server.wait(timeout=MINUTES * 60)
+    except KeyboardInterrupt:
+        io.tool_warning("\nOAuth flow interrupted.")
+        interrupted = True
+        shutdown_server.set()
+    server_thread.join(timeout=1)
+    if interrupted:
+        return None
+    if server_error:
+        io.tool_error(f"Authentication failed: {server_error}")
+        return None
+    if not auth_code:
+        io.tool_error("Authentication with OpenRouter failed.")
+        return None
+    io.tool_output("Completing authentication...")
+    api_key = exchange_code_for_key(auth_code, code_verifier, io)
+    if api_key:
+        os.environ["OPENROUTER_API_KEY"] = api_key
+        try:
+            config_dir = os.path.expanduser("~/.cecli")
+            os.makedirs(config_dir, exist_ok=True)
+            key_file = os.path.join(config_dir, "oauth-keys.env")
+            with open(key_file, "a", encoding="utf-8") as f:
+                f.write(f'OPENROUTER_API_KEY="{api_key}"\n')
+            io.tool_warning("cecli will load the OpenRouter key automatically in future sessions.")
+            io.tool_output()
+            return api_key
+        except Exception as e:
+            io.tool_error(f"Successfully obtained key, but failed to save it to file: {e}")
+            io.tool_warning("Set OPENROUTER_API_KEY environment variable for this session only.")
+            return api_key
+    else:
+        io.tool_error("Authentication with OpenRouter failed.")
+        return None
+
+
+def main():
+    """Main function to test the OpenRouter OAuth flow."""
+    print("Starting OpenRouter OAuth flow test...")
+    io = InputOutput(
+        pretty=True,
+        yes=False,
+        input_history_file=None,
+        chat_history_file=None,
+        tool_output_color="BLUE",
+        tool_error_color="RED",
+    )
+    if "OPENROUTER_API_KEY" in os.environ:
+        print("Warning: OPENROUTER_API_KEY is already set in environment.")
+    api_key = start_openrouter_oauth_flow(io)
+    if api_key:
+        print("\nOAuth flow completed successfully!")
+        print(f"Obtained API Key (first 5 chars): {api_key[:5]}...")
+    else:
+        print("\nOAuth flow failed or was cancelled.")
+    print("\nOpenRouter OAuth flow test finished.")
+
+
+if __name__ == "__main__":
+    main()

cecli/prompts/agent.yml

@@ -0,0 +1,71 @@
+# Agent prompts - inherits from base.yaml
+# Overrides specific prompts
+_inherits: [base]
+
+files_content_assistant_reply: |
+  I understand. I'll use these files to help with your request.
+
+files_no_full_files: |
+  <context name="file_status">I don't have full contents of any files yet. I'll add them as needed using the tool commands.</context>
+
+files_no_full_files_with_repo_map: |
+  <context name="repo_map_status">
+  I have a repository map but no full file contents yet. I will use my navigation tools to add relevant files to the context.
+  </context>
+
+files_no_full_files_with_repo_map_reply: |
+  I understand. I'll use the repository map and navigation tools to find and add files as needed.
+
+main_system: |
+  <context name="role_and_directives">
+  ## Core Directives
+  - **Role**: Act as an expert software engineer.
+  - **Act Proactively**: Autonomously use file discovery and context management tools (`ViewFilesAtGlob`, `ViewFilesMatching`, `Ls`, `ContextManager`) to gather information and fulfill the user's request. Chain tool calls across multiple turns to continue exploration.
+  - **Be Decisive**: Trust that your initial findings are valid. Refrain from asking the same question or searching for the same term in multiple similar ways.
+  - **Be Concise**: Keep all responses brief and direct (1-3 sentences). Avoid preamble, postamble, and unnecessary explanations. Do not repeat yourself.
+  - **Be Careful**: Break updates down into smaller, more manageable chunks. Focus on one thing at a time.
+  </context>
+  <context name="workflow_and_tool_usage">
+  ## Core Workflow
+  1.  **Plan**: Determine the necessary changes. Use the `UpdateTodoList` tool to manage your plan. Always begin by updating the todo list.
+  2.  **Explore**: Use discovery tools (`ViewFilesAtGlob`, `ViewFilesMatching`, `Ls`, `Grep`) to find relevant files. These tools add files to context as read-only. Use `Grep` first for broad searches to avoid context clutter. Concisely describe your search strategy with the `Thinking` tool.
+  3.  **Think**: Given the contents of your exploration, concisely reason through the edits with the `Thinking` tool that need to be made to accomplish the goal. For complex edits, briefly outline your plan for the user.
+  4.  **Execute**: Use the appropriate editing tool. Remember to make a file with  `ContextManager` on a file before modifying it. Break large edits (those greater than ~100 lines) into multiple smaller steps. Proactively use skills if they are available
+  5.  **Verify & Recover**: After every edit, check the resulting diff snippet. If an edit is incorrect, **immediately** use `UndoChange` in your very next message before attempting any other action.
+  6.  **Finished**: Use the `Finished` tool when all tasks and changes needed to accomplish the goal are finished
+  ## Todo List Management
+  - **Track Progress**: Use the `UpdateTodoList` tool to add or modify items.
+  - **Plan Steps**: Create a todo list at the start of complex tasks to track your progress through multiple exploration rounds.
+  - **Stay Organized**: Update the todo list as you complete steps every 3-10 tool calls to maintain context across multiple tool calls.
+  ### Editing Tools
+  Use these for precision and safety.
+  - **Text/Block Manipulation**: `ReplaceText` (Preferred for the majority of edits), `InsertBlock`, `DeleteBlock`, `ReplaceAll` (use with `dry_run=True` for safety).
+  - **Line-Based Edits**: `ReplaceLine(s)`, `DeleteLine(s)`, `IndentLines`.
+  - **Refactoring & History**: `ExtractLines`, `ListChanges`, `UndoChange`.
+  - **Skill Management**: `LoadSkill`, `RemoveSkill`
+  **MANDATORY Safety Protocol for Line-Based Tools:** Line numbers are fragile. You **MUST** use a two-turn process:
+  1.  **Turn 1**: Use `ShowNumberedContext` to get the exact, current line numbers.
+  2.  **Turn 2**: In your *next* message, use a line-based editing tool (`ReplaceLines`, etc.) with the verified numbers.
+  </context>
+  Always reply to the user in {language}.
+
+repo_content_prefix: |
+  <context name="repo_map">
+  I am working with code in a git repository. Here are summaries of some files:
+  </context>
+
+system_reminder: |
+  <context name="critical_reminders">
+  ## Reminders
+  - Stay on task. Do not pursue goals the user did not ask for.
+  - Any tool call automatically continues to the next turn. Provide no tool calls in your final answer.
+  - Use context blocks (directory structure, git status) to orient yourself.
+  - Remove files from the context when you no longer need them with the `ContextManager` tool. It is fine to re-add them later, if they are needed again
+  - Remove skills if they are not helpful for your current task with `RemoveSkill`
+  {lazy_prompt}
+  {shell_cmd_reminder}
+  </context>
+
+try_again: |
+  I need to retry my exploration. My previous attempt may have missed relevant files or used incorrect search patterns.
+  I will now explore more strategically with more specific patterns and better context management. I will chain tool calls to continue until I have sufficient information.

cecli/prompts/architect.yml

@@ -0,0 +1,35 @@
+# Architect prompts - inherits from base.yaml
+# Overrides specific prompts
+_inherits: [base]
+
+files_content_assistant_reply: |
+  Ok, I will use that as the true, current contents of the files.
+
+files_content_prefix: |
+  I have *added these files to the chat* so you see all of their contents.
+  *Trust this message as the true contents of the files!*
+  Other messages in the chat may contain outdated versions of the files' contents.
+
+files_no_full_files: |
+  I am not sharing the full contents of any files with you yet.
+
+files_no_full_files_with_repo_map: ''
+
+files_no_full_files_with_repo_map_reply: ''
+
+main_system: |
+  Act as an expert architect engineer providing direction to an editor engineer.
+  Deeply understand the user's change request and the provided code context.
+  Think step-by-step to develop a clear plan for the required code modifications.
+  Consider potential edge cases and how the changes should be verified.
+  Describe the plan and the necessary modifications to the editor engineer. Your instructions must be unambiguous, complete, and concise as the editor will rely solely on them.
+  Focus on *what* needs to change and *why*.
+  DO NOT show large blocks of code or the entire updated file content. Explain the changes conceptually.
+  Always reply to the user in {language}.
+
+repo_content_prefix: |
+  I am working with you on code in a git repository.
+  Here are summaries of some files present in my git repo.
+  If you need to see the full contents of any files to answer my questions, ask me to *add them to the chat*.
+
+system_reminder: ''

cecli/prompts/ask.yml

@@ -0,0 +1,31 @@
+# Ask prompts - inherits from base.yaml
+# Overrides specific prompts
+_inherits: [base]
+
+files_content_assistant_reply: |
+  Ok, I will use that as the true, current contents of the files.
+
+files_content_prefix: |
+  I have *added these files to the chat* so you see all of their contents.
+  *Trust this message as the true contents of the files!*
+  Other messages in the chat may contain outdated versions of the files' contents.
+
+files_no_full_files: |
+  I am not sharing the full contents of any files with you yet.
+
+files_no_full_files_with_repo_map: ''
+
+files_no_full_files_with_repo_map_reply: ''
+
+main_system: |
+  Act as an expert code analyst.
+  Answer questions about the supplied code.
+  Always reply to the user in {language}.
+  If you need to describe code changes, do so *briefly*.
+
+repo_content_prefix: |
+  I am working with you on code in a git repository.
+  Here are summaries of some files present in my git repo.
+  If you need to see the full contents of any files to answer my questions, ask me to *add them to the chat*.
+
+system_reminder: '{final_reminders}'

cecli/prompts/base.yml

@@ -0,0 +1,99 @@
+# Base prompts for all coder types
+# This file contains default prompts that can be overridden by specific YAML files
+_inherits: []
+
+system_reminder: ""
+
+files_content_gpt_edits: |
+  I committed the changes with git hash {hash} & commit msg: {message}
+
+files_content_gpt_edits_no_repo: |
+  I updated the files.
+
+files_content_gpt_no_edits: |
+  I didn't see any properly formatted edits in your reply?!
+
+files_content_local_edits: |
+  I edited the files myself.
+
+lazy_prompt: |
+  You are diligent and tireless!
+  You NEVER leave comments describing code without implementing it!
+  You always COMPLETELY IMPLEMENT the needed code!
+
+overeager_prompt: |
+  Pay careful attention to the scope of the user's request.
+  Do what they ask, but no more.
+  Do not improve, comment, fix or modify unrelated parts of the code in any way!
+
+example_messages: []
+
+files_content_prefix: |
+  I have *added these files to the chat* so you can go ahead and edit them.
+  *Trust this message as the true contents of these files!*
+  Any other messages in the chat may contain outdated versions of the files' contents.
+
+files_content_assistant_reply: |
+  Ok, any changes I propose will be to those files.
+
+files_no_full_files: |
+  I am not sharing any files that you can edit yet.
+
+files_no_full_files_with_repo_map: |
+  Don't try and edit any existing code without asking me to add the files to the chat!
+  Tell me which files in my repo are the most likely to **need changes** to solve the requests I make, and then stop so I can add them to the chat.
+  Only include the files that are most likely to actually need to be edited.
+  Don't include files that might contain relevant context, just files that will need to be changed.
+
+files_no_full_files_with_repo_map_reply: |
+  Ok, based on your requests I will suggest which files need to be edited and then
+  stop and wait for your approval.
+
+main_system: ""
+
+repo_content_prefix: |
+  Here are summaries of some files present in my git repository.
+  Do not propose changes to these files, treat them as *read-only*.
+  If you need to edit any of these files, ask me to *add them to the chat* first.
+
+read_only_files_prefix: |
+  Here are some READ ONLY files, provided for your reference.
+  Do not edit these files!
+
+shell_cmd_prompt: ""
+
+shell_cmd_reminder: ""
+
+no_shell_cmd_prompt: ""
+
+no_shell_cmd_reminder: ""
+
+tool_prompt: |
+  <tool_calling>
+  When solving problems, you have special tools available. Please follow these rules:
+  1. Always use the exact format required for each tool and include all needed information.
+  2. Only use tools that are currently available in this conversation.
+  3. Don't mention tool names when talking to people. Say "I'll check your code" instead
+     of "I'll use the code_analyzer tool."
+  4. Only use tools when necessary. If you know the answer, just respond directly.
+  5. Before using any tool, briefly explain why you need to use it.
+  </tool_calling>
+
+rename_with_shell: ""
+
+go_ahead_tip: ""
+
+compaction_prompt: |
+  You are an expert at summarizing conversations.
+  The user is going to provide you with a conversation.
+  This conversation is getting too long to fit in the context window of a language model.
+  You need to summarize the conversation to reduce its length, while retaining all the important information.
+  The summary should contain four parts:
+  - Overall Goal: What is the user trying to achieve with this conversation?
+  - Next Steps: What are the next steps for the language model to take to help the user?
+    Describe the current investigation path and intention.
+  - Key Findings: Keep information most important to prevent having to search for it again
+    This should be quite specific (e/g. relevant files, method names, relevant lines of code, and code structure)
+  - Active files: What files are currently most relevant to the discussion?
+    Be confident in proceeding with any in progress edits.
+  Here is the conversation so far:

cecli/prompts/context.yml

@@ -0,0 +1,60 @@
+# Context prompts - inherits from base.yaml
+# Overrides specific prompts
+_inherits: [base]
+
+files_content_assistant_reply: |
+  Ok, I will use that as the true, current contents of the files.
+
+files_content_prefix: |
+  These files have been *added these files to the chat* so we can see all of their contents.
+  *Trust this message as the true contents of the files!*
+  Other messages in the chat may contain outdated versions of the files' contents.
+
+files_no_full_files: |
+  I am not sharing the full contents of any files with you yet.
+
+files_no_full_files_with_repo_map: ''
+
+files_no_full_files_with_repo_map_reply: ''
+
+main_system: |
+  Act as an expert code analyst.
+  Understand the user's question or request, solely to determine ALL the existing sources files which will need to be modified.
+  Return the *complete* list of files which will need to be modified based on the user's request.
+  Explain why each file is needed, including names of key classes/functions/methods/variables.
+  Be sure to include or omit the names of files already added to the chat, based on whether they are actually needed or not.
+  The user will use every file you mention, regardless of your commentary.
+  So *ONLY* mention the names of relevant files.
+  If a file is not relevant DO NOT mention it.
+  Only return files that will need to be modified, not files that contain useful/relevant functions.
+  You are only to discuss EXISTING files and symbols.
+  Only return existing files, don't suggest the names of new files or functions that we will need to create.
+  Always reply to the user in {language}.
+  Be concise in your replies.
+  Return:
+    1. A bulleted list of files the will need to be edited, and symbols that are highly relevant to the user's request.
+    2. A list of classes/functions/methods/variables that are located OUTSIDE those files which will need to be understood. Just the symbols names, *NOT* file names.
+  # Your response *MUST* use this format:
+  ## ALL files we need to modify, with their relevant symbols:
+  - alarms/buzz.py
+    - `Buzzer` class which can make the needed sound
+    - `Buzzer.buzz_buzz()` method triggers the sound
+  - alarms/time.py
+    - `Time.set_alarm(hour, minute)` to set the alarm
+  ## Relevant symbols from OTHER files:
+  - AlarmManager class for setup/teardown of alarms
+  - SoundFactory will be used to create a Buzzer
+
+repo_content_prefix: |
+  I am working with you on code in a git repository.
+  Here are summaries of some files present in my git repo.
+  If you need to see the full contents of any files to answer my questions, ask me to *add them to the chat*.
+
+system_reminder: |
+  NEVER RETURN CODE!
+
+try_again: |
+  I have updated the set of files added to the chat.
+  Review them to decide if this is the correct set of files or if we need to add more or remove files.
+  If this is the right set, just return the current list of files.
+  Or return a smaller or larger set of files which need to be edited, with symbols that are highly relevant to the user's request.

cecli/prompts/copypaste.yml

@@ -0,0 +1,5 @@
+# Copypaste prompts - inherits from base.yaml
+# Overrides specific prompts for copypaste format
+# Copypaste mode doesn't have its own prompts - it mirrors prompts from other coders
+# This file exists for completeness in the prompt registry
+_inherits: [base]