Use normalize_filepath across all tools that work with filepaths

This change ensures consistent filepath handling across all toolkit functions by using the normalize_filepath utility function. This handles URL-encoded paths, relative paths, and special characters consistently.

- Updated file_system toolkit: read, write, edit, search_and_replace, glob, grep, ls
- Updated notebook toolkit: all functions that take file_path parameter
- Updated git toolkit: all functions that take path parameter
- Added comprehensive tests for normalize_filepath functionality

All tools now properly decode URL-encoded paths (e.g., my%20notebook.ipynb → my notebook.ipynb) and resolve relative paths against the Jupyter server's root directory.

Author: Zsailer

jupyter_ai_tools/toolkits/file_system.py

@@ -8,6 +8,8 @@
 
 from jupyter_ai.tools.models import Tool, Toolkit
 
+from ..utils import normalize_filepath
+
 
 def read(file_path: str, offset: Optional[int] = None, limit: Optional[int] = None) -> str:
     """Reads a file from the local filesystem
@@ -21,6 +23,7 @@ def read(file_path: str, offset: Optional[int] = None, limit: Optional[int] = No
         The contents of the file, potentially with line numbers
     """
     try:
+        file_path = normalize_filepath(file_path)
         if not os.path.exists(file_path):
             return f"Error: File not found: {file_path}"
 
@@ -73,6 +76,7 @@ def write(file_path: str, content: str) -> str:
         A success message or error message
     """
     try:
+        file_path = normalize_filepath(file_path)
         # Ensure the directory exists
         directory = os.path.dirname(file_path)
         if directory and not os.path.exists(directory):
@@ -107,6 +111,7 @@ def edit(file_path: str, old_string: str, new_string: str, replace_all: bool = F
         A success message or error message
     """
     try:
+        file_path = normalize_filepath(file_path)
         if not os.path.exists(file_path):
             return f"Error: File not found: {file_path}"
 
@@ -159,6 +164,7 @@ async def search_and_replace(
         A success message or error message
     """
     try:
+        file_path = normalize_filepath(file_path)
         if not os.path.exists(file_path):
             return f"Error: File not found: {file_path}"
 
@@ -212,7 +218,7 @@ async def glob(pattern: str, path: Optional[str] = None) -> str:
         A list of matching file paths sorted by modification time
     """
     try:
-        search_path = path or os.getcwd()
+        search_path = normalize_filepath(path) if path else os.getcwd()
         if not os.path.exists(search_path):
             return f"Error: Path not found: {search_path}"
 
@@ -260,7 +266,7 @@ async def grep(
         A list of file paths with at least one match
     """
     try:
-        search_path = path or os.getcwd()
+        search_path = normalize_filepath(path) if path else os.getcwd()
         if not os.path.exists(search_path):
             return [f"Error: Path not found: {search_path}"]
 
@@ -312,6 +318,7 @@ async def ls(path: str, ignore: Optional[List[str]] = None) -> str:
         A list of files and directories in the given path
     """
     try:
+        path = normalize_filepath(path)
         if not os.path.exists(path):
             return f"Error: Path not found: {path}"
 

jupyter_ai_tools/toolkits/git.py

@@ -4,6 +4,8 @@
 from jupyter_ai.tools.models import Tool, Toolkit
 from jupyterlab_git.git import Git
 
+from ..utils import normalize_filepath
+
 git = Git()
 
 
@@ -19,6 +21,7 @@ async def git_clone(path: str, url: str) -> str:
     Returns:
         str: Success or error message.
     """
+    path = normalize_filepath(path)
     res = await git.clone(path, repo_url=url)
     if res["code"] == 0:
         return f"✅ Cloned repo into {res['path']}"
@@ -36,6 +39,7 @@ async def git_status(path: str) -> str:
     Returns:
         str: A JSON-formatted string of status or an error message.
     """
+    path = normalize_filepath(path)
     res = await git.status(path)
     if res["code"] == 0:
         return f"📋 Status:\n{json.dumps(res, indent=2)}"
@@ -54,6 +58,7 @@ async def git_log(path: str, history_count: int = 10) -> str:
     Returns:
         str: A JSON-formatted commit log or error message.
     """
+    path = normalize_filepath(path)
     res = await git.log(path, history_count=history_count)
     if res["code"] == 0:
         return f"🕓 Recent commits:\n{json.dumps(res, indent=2)}"
@@ -71,6 +76,7 @@ async def git_pull(path: str) -> str:
     Returns:
         str: Success or error message.
     """
+    path = normalize_filepath(path)
     res = await git.pull(path)
     return (
         "✅ Pulled latest changes."
@@ -91,6 +97,7 @@ async def git_push(path: str, branch: str) -> str:
     Returns:
         str: Success or error message.
     """
+    path = normalize_filepath(path)
     res = await git.push(remote="origin", branch=branch, path=path)
     return (
         "✅ Pushed changes."
@@ -111,6 +118,7 @@ async def git_commit(path: str, message: str) -> str:
     Returns:
         str: Success or error message.
     """
+    path = normalize_filepath(path)
     res = await git.commit(commit_msg=message, amend=False, path=path)
     return (
         "✅ Commit successful."
@@ -132,6 +140,7 @@ async def git_add(path: str, add_all: bool = True, filename: str = "") -> str:
     Returns:
         str: Success or error message.
     """
+    path = normalize_filepath(path)
     if add_all:
         res = await git.add_all(path)
     elif filename:
@@ -158,6 +167,7 @@ async def git_get_repo_root(path: str) -> str:
     Returns:
         str: The path to the Git repository root or an error message.
     """
+    path = normalize_filepath(path)
     dir_path = os.path.dirname(path)
     res = await git.show_top_level(dir_path)
     if res["code"] == 0 and res.get("path"):

jupyter_ai_tools/toolkits/notebook.py

@@ -13,6 +13,7 @@
     cell_to_md,
     get_file_id,
     get_jupyter_ydoc,
+    normalize_filepath,
     notebook_json_to_md,
 )
 
@@ -70,6 +71,7 @@ async def read_notebook(file_path: str, include_outputs=False) -> str:
         The notebook content as a markdown string.
     """
     try:
+        file_path = normalize_filepath(file_path)
         notebook_dict = await read_notebook_json(file_path)
         notebook_md = notebook_json_to_md(notebook_dict, include_outputs=include_outputs)
         return notebook_md
@@ -91,6 +93,7 @@ async def read_notebook_json(file_path: str) -> Dict[str, Any]:
         A dictionary containing the complete notebook structure.
     """
     try:
+        file_path = normalize_filepath(file_path)
         with open(file_path, "r", encoding="utf-8") as f:
             notebook_dict = json.load(f)
             return notebook_dict
@@ -120,6 +123,7 @@ async def read_cell(file_path: str, cell_id: str, include_outputs: bool = True)
         LookupError: If no cell with the given ID is found.
     """
     try:
+        file_path = normalize_filepath(file_path)
         # Resolve cell_id in case it's an index
         resolved_cell_id = await _resolve_cell_id(file_path, cell_id)
         cell, cell_index = await read_cell_json(file_path, resolved_cell_id)
@@ -150,6 +154,7 @@ async def read_cell_json(file_path: str, cell_id: str) -> Tuple[Dict[str, Any],
         LookupError: If no cell with the given ID is found.
     """
     try:
+        file_path = normalize_filepath(file_path)
         # Resolve cell_id in case it's an index
         resolved_cell_id = await _resolve_cell_id(file_path, cell_id)
         notebook_json = await read_notebook_json(file_path)
@@ -182,7 +187,7 @@ async def get_cell_id_from_index(file_path: str, cell_index: int) -> str:
         or if the cell does not have an ID.
     """
     try:
-        
+        file_path = normalize_filepath(file_path)
         cell_id = None
         notebook_json = await read_notebook_json(file_path)
         cells = notebook_json["cells"]
@@ -233,7 +238,7 @@ async def add_cell(
         None
     """
     try:
-        
+        file_path = normalize_filepath(file_path)
         # Resolve cell_id in case it's an index
         resolved_cell_id = await _resolve_cell_id(file_path, cell_id) if cell_id else None
 
@@ -304,7 +309,7 @@ async def insert_cell(
         None
     """
     try:
-        
+        file_path = normalize_filepath(file_path)
         file_id = await get_file_id(file_path)
         ydoc = await get_jupyter_ydoc(file_id)
 
@@ -357,7 +362,7 @@ async def delete_cell(file_path: str, cell_id: str):
         None
     """
     try:
-        
+        file_path = normalize_filepath(file_path)
         # Resolve cell_id in case it's an index
         resolved_cell_id = await _resolve_cell_id(file_path, cell_id)
 
@@ -762,7 +767,7 @@ async def edit_cell(file_path: str, cell_id: str, content: str) -> None:
         ValueError: If the cell_id is not found in the notebook.
     """
     try:
-        
+        file_path = normalize_filepath(file_path)
         # Resolve cell_id in case it's an index
         resolved_cell_id = await _resolve_cell_id(file_path, cell_id)
 
@@ -814,7 +819,7 @@ def read_cell_nbformat(file_path: str, cell_id: str) -> Dict[str, Any]:
     Raises:
         ValueError: If no cell with the given ID is found.
     """
-
+    file_path = normalize_filepath(file_path)
     with open(file_path, "r", encoding="utf-8") as f:
         notebook = nbformat.read(f, as_version=nbformat.NO_CONVERT)
 

jupyter_ai_tools/utils.py

@@ -1,20 +1,72 @@
 import functools
 import inspect
+import os
 import typing
+from pathlib import Path
 from typing import Optional
+from urllib.parse import unquote
 
 from jupyter_server.serverapp import ServerApp
 from jupyter_server.auth.identity import User
 from pycrdt import Awareness
 
 
-async def get_serverapp():
+def get_serverapp():
     """Returns the server app from the request context"""
 
     server = ServerApp.instance()
     return server
 
 
+def normalize_filepath(file_path: str) -> str:
+    """
+    Normalizes a file path for Jupyter applications to return an absolute path.
+    
+    Handles various input formats:
+    - Relative paths from current working directory
+    - URL-encoded relative paths (common in Jupyter contexts)
+    - Absolute paths (returned as-is after normalization)
+    
+    Args:
+        file_path: Path in any of the supported formats
+        
+    Returns:
+        Absolute path to the file
+        
+    Example:
+        >>> normalize_filepath("notebooks/my%20notebook.ipynb")
+        "/current/working/dir/notebooks/my notebook.ipynb"
+        >>> normalize_filepath("/absolute/path/file.ipynb")
+        "/absolute/path/file.ipynb"
+        >>> normalize_filepath("relative/file.ipynb")
+        "/current/working/dir/relative/file.ipynb"
+    """
+    if not file_path or not file_path.strip():
+        raise ValueError("file_path cannot be empty")
+    
+    # URL decode the path in case it contains encoded characters
+    decoded_path = unquote(file_path)
+    
+    # Convert to Path object for easier manipulation
+    path = Path(decoded_path)
+    
+    # If already absolute, just normalize and return
+    if path.is_absolute():
+        return str(path.resolve())
+    
+    # For relative paths, get the Jupyter server's root directory
+    try:
+        serverapp = get_serverapp()
+        root_dir = serverapp.root_dir
+    except Exception:
+        # Fallback to current working directory if server app is not available
+        root_dir = os.getcwd()
+    
+    # Resolve relative path against the root directory
+    resolved_path = Path(root_dir) / path
+    return str(resolved_path.resolve())
+
+
 async def get_jupyter_ydoc(file_id: str):
     """Returns the notebook ydoc
 
@@ -24,7 +76,7 @@ async def get_jupyter_ydoc(file_id: str):
     Returns:
         `YNotebook` ydoc for the notebook
     """
-    serverapp = await get_serverapp()
+    serverapp = get_serverapp()
     yroom_manager = serverapp.web_app.settings["yroom_manager"]
     room_id = f"json:notebook:{file_id}"
 
@@ -35,7 +87,7 @@ async def get_jupyter_ydoc(file_id: str):
 
 
 async def get_global_awareness() -> Optional[Awareness]:
-    serverapp = await get_serverapp()
+    serverapp = get_serverapp()
     yroom_manager = serverapp.web_app.settings["yroom_manager"]
 
     room_id = "JupyterLab:globalAwareness" 
@@ -57,10 +109,11 @@ async def get_file_id(file_path: str) -> str:
     Returns:
         The file ID of the document
     """
-
-    serverapp = await get_serverapp()
+    normalized_file_path = normalize_filepath(file_path)
+    
+    serverapp = get_serverapp()
     file_id_manager = serverapp.web_app.settings["file_id_manager"]
-    file_id = file_id_manager.get_id(file_path)
+    file_id = file_id_manager.get_id(normalized_file_path)
 
     return file_id
 
@@ -100,7 +153,7 @@ async def wrapper(*args, **kwargs):
 
             # Get serverapp for logging
             try:
-                serverapp = await get_serverapp()
+                serverapp = get_serverapp()
                 logger = serverapp.log
             except Exception:
                 logger = None