xlwings-server 1.1.0__py3-none-any.whl

xlwings_server/.env.template

@@ -0,0 +1,145 @@
+# Get a free trial key from https://www.xlwings.org/trial
+XLWINGS_LICENSE_KEY="your_license_key"
+
+# Use one of "dev", "qa", "uat", "staging", or "prod". "dev" will activate hotreload for
+# the task pane and other dev-specific features. This setting also takes care of loading
+# the correct ID in the manifest. Except for "prod", the environment name will show up
+# in the add-in name (ProjectName [dev]) and custom functions (NAMESPACE_DEV.MYFUNC)
+XLWINGS_ENVIRONMENT="dev"
+
+# Secret key is generated by "xlwings-server init"
+XLWINGS_SECRET_KEY=""
+
+# This sets the HTTP response headers recommended by OWASP. Some of the headers have to
+# be less restrictive if XLWINGS_ENABLE_EXCEL_ONLINE=true. Note that this only applies
+# to xlwings Server, not xlwings Wasm.
+# XLWINGS_ADD_SECURITY_HEADERS=true
+
+# If you mount xlwings Server on a non-root path (e.g., https://my.domain.com/myapp)
+# via a reverse proxy such as nginx, you need to set this to: "/myapp". You most likely
+# also need to set the XLWINGS_STATIC_URL_PATH="/myapp/static"
+# XLWINGS_APP_PATH=""
+
+# To authenticate users, provide the Auth providers as list.
+# E.g, to enable Entra ID SSO auth: XLWINGS_AUTH_PROVIDERS=["entraid"]. If you want
+# to accept multipe authentication methods, you will need the name as
+# Auth-Provider header from the client.
+# XLWINGS_AUTH_PROVIDERS=[]
+
+# Enable Single Sign-On (SSO) via Microsoft Entra ID (previously Azure AD)
+# XLWINGS_AUTH_ENTRAID_CLIENT_ID=
+# XLWINGS_AUTH_ENTRAID_TENANT_ID=
+
+# RBAC (role-based access control)
+# If your auth provider supports roles, you can list the required roles here.
+# E.g.: XLWINGS_AUTH_REQUIRED_ROLES=["xlwings.user"]
+# XLWINGS_AUTH_REQUIRED_ROLES=[]
+
+# Set this to true if you have users from external organizations
+# XLWINGS_AUTH_ENTRAID_MULTITENANT=false
+
+# If the add-in will be distributed via Microsoft's public add-in store, set this to
+# true to load office.js via their CDN
+# XLWINGS_CDN_OFFICEJS=false
+
+# By default, xlwings Wasm uses the CDN for Pyodide. If you set this to false,
+# Excel won't require any connection to the public Internet as everything will be served
+# from the static file server. This, however, requires you to provide all Python wheels
+# via the app/static/vendors/pyodide folder.
+# XLWINGS_CDN_PYODIDE=true
+
+# If you use the Office Scripts integration or custom functions in Excel on the web,
+# you need to set this to ["*"]. Otherwise you should disable it by setting it to [].
+XLWINGS_CORS_ALLOW_ORIGINS=["*"]
+
+# Maximum number of retry attempts for failed custom function requests
+# XLWINGS_CUSTOM_FUNCTIONS_MAX_RETRIES=3
+
+# HTTP status codes that should trigger retries for custom function requests
+# XLWINGS_CUSTOM_FUNCTIONS_RETRY_CODES=[500, 502, 504]
+
+# This allows you to override the date format for custom functions globally.
+# Example: XLWINGS_DATE_FORMAT="m/d/yyyy"
+# XLWINGS_DATE_FORMAT=
+
+# Task pane HTML file
+# XLWINGS_TASKPANE_HTML="taskpane.html"
+
+# This loads Alpine.js (CSP build) for client-side interactions
+# see: https://alpinejs.dev/advanced/csp
+# XLWINGS_ENABLE_ALPINEJS_CSP=true
+
+# This loads Bootstrap with the xlwings theme
+# XLWINGS_ENABLE_BOOTSTRAP=true
+
+# Excel on the web requires less strict security headers
+# XLWINGS_ENABLE_EXCEL_ONLINE=true
+
+# Enables hot reloading of Office.js add-ins.
+# Requires XLWINGS_ENVIRONMENT="dev" and XLWINGS_ENABLE_SOCKETIO=true.
+# XLWINGS_ENABLE_HOTRELOAD=true
+
+# This loads htmx for client-server interaction, see https://htmx.org
+# XLWINGS_ENABLE_HTMX=true
+
+# If true, it uses xlwings Wasm instead of xlwings Server. This will use Python
+# via WASM and won't require a Python installation on the backend. This allows you to
+# deploy the add-in to a static file server such as GitHub Pages or Cloudflare Pages.
+# XLWINGS_ENABLE_WASM=false
+
+# This loads Socket.io, which is required for streaming custom functions
+# and can be used for realtime interaction on the task pane. Note that this must also
+# be true to enable hotreloading of the taskpane during development.
+# XLWINGS_ENABLE_SOCKETIO=true
+
+# Provide custom headers in the form {"header1": "value1", "header2": "value2"}. E.g. for CSP header:
+# {"Content-Security-Policy": "default-src 'self'; form-action 'self'; object-src 'none'; frame-ancestors 'none'; upgrade-insecure-requests; block-all-mixed-content; img-src 'self' data:"}
+# For Excel online, you need to remove "frame-ancestors 'none' and append: "; font-src 'self' https://res-1.cdn.office.net; style-src 'self' 'unsafe-inline'"
+# With XLWINGS_CDN_OFFICEJS=true, you need to append "; script-src 'self' https://appsforoffice.microsoft.com;"
+# XLWINGS_CUSTOM_HEADERS={}
+
+# This will be prepended to all custom functions, e.g., "XLWINGS.MYFUNC". Note that
+# if the environment is not "prod", it will append the environment to the namespace,
+# e.g., XLWINGS_DEV to prevent name clashes when you have the same add-in from multiple
+# environments installed.
+# XLWINGS_FUNCTIONS_NAMESPACE="XLWINGS"
+
+# In case xlwings Server doesn't manage to get the URL correct under /manifest, you
+# can set the proper hostname here, e.g., mydomain.com (without the https://)
+# XLWINGS_HOSTNAME=
+
+# Set the log level to "DEBUG" for more details, but this can log sensitive tokens!
+# XLWINGS_LOG_LEVEL="INFO"
+
+# A Redis URL for the caching of object handles. Required for production use.
+# Example: redis://host:6379/0 or rediss://host:6379/0
+# XLWINGS_OBJECT_CACHE_URL=
+
+# This setting expects a cron expression that determines when objects that are cached
+# via object handles should be purged from the cache. This requires
+# XLWINGS_OBJECT_CACHE_URL to be configured. By default, the object cache is purged
+# every Saturday at 12:00 PM (UTC).
+# XLWINGS_OBJECT_CACHE_EXPIRE_AT="0 12 * * sat"
+
+# If true, cached objects (via object handles) will be compressed when stored in Redis.
+# This requires XLWINGS_OBJECT_CACHE_URL to be configured.
+# XLWINGS_OBJECT_CACHE_ENABLE_COMPRESSION=true
+
+# This will determine the name of the add-in. If the environment is not "prod", the name
+# of the environment will be shown like this: Project Name [dev].
+# XLWINGS_PROJECT_NAME=""
+
+# Number of seconds after which requests to the backend will timeout
+# XLWINGS_REQUEST_TIMEOUT=300
+
+# If you run the Socket.IO server in an own process, you need to configure a message
+# queue, such as Redis/Valkey. E.g.: redis://host:6379/0
+# XLWINGS_SOCKETIO_MESSAGE_QUEUE_URL=
+
+# If you run the Socket.IO server in an own process, you need to set this to true for
+# ONLY (!) the app that represents the Socket.IO server.
+# XLWINGS_SOCKETIO_SERVER_APP=false
+
+# The absolute path to the static files. If you set XLWINGS_APP_PATH to "/myapp", you
+# likely need to change this to "/myapp/static".
+# XLWINGS_STATIC_URL_PATH="/static"

xlwings_server/__init__.py

@@ -0,0 +1,12 @@
+from pathlib import Path
+
+try:
+    from ._version import __version__
+except ImportError:
+    __version__ = "0.0.0"
+
+# Store package directory for use throughout the application
+# This is evaluated when the package is first imported, before any sys.path manipulation
+PACKAGE_DIR = Path(__file__).parent.resolve()
+
+from .config import settings  # noqa: E402

xlwings_server/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '1.1.0'
+__version_tuple__ = version_tuple = (1, 1, 0)
+
+__commit_id__ = commit_id = None

xlwings_server/auth/custom/__init__.py

@@ -0,0 +1,26 @@
+import logging
+import secrets
+
+from aiocache import cached
+from fastapi import status
+from fastapi.exceptions import HTTPException
+
+from xlwings_server.models import User
+
+logger = logging.getLogger(__name__)
+
+
+@cached(ttl=60 * 60)
+async def validate_token(token_string: str):
+    """token_string has to be delivered via the Authorization header from Excel. The
+    Authorization header is set by implementing the globalThis.getAuth() function
+    under static/js/auth.js.
+    See https://server.xlwings.org/en/latest/auth_providers/#custom-authentication
+    """
+    if secrets.compare_digest(token_string, "test-token"):  # TODO: implement
+        return User(id="customid", name="custom user")
+    else:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Custom Auth Error: Couldn't validate token",
+        )

xlwings_server/auth/entraid/__init__.py

@@ -0,0 +1,131 @@
+"""
+See https://learn.microsoft.com/en-us/entra/identity-platform/access-tokens
+"""
+
+import logging
+import re
+
+import httpx
+from aiocache import cached
+from fastapi import Depends, Header, status
+from fastapi.exceptions import HTTPException
+from joserfc import jwt
+from joserfc.jwk import KeySet
+from joserfc.jwt import JWTClaimsRegistry
+
+from ... import models
+from ...config import settings
+
+# Try to import jwks from project directory first (user override)
+# Fall back to package location (default implementation)
+try:
+    from auth.entraid import jwks
+except ModuleNotFoundError:
+    from . import jwks
+
+logger = logging.getLogger(__name__)
+
+OPENID_CONNECT_DISCOVERY_DOCUMENT_URL = (
+    "https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration"
+)
+
+
+@cached(ttl=60 * 60 * 24)
+async def get_jwks_json_default():
+    logger.info("Get default JWKS json for Entra ID")
+    async with httpx.AsyncClient() as client:
+        response = await client.get(OPENID_CONNECT_DISCOVERY_DOCUMENT_URL)
+    jwks_uri = response.json()["jwks_uri"]
+    async with httpx.AsyncClient() as client:
+        response = await client.get(jwks_uri)
+    return response.json()
+
+
+async def get_key_set():
+    jwks_data = await jwks.get_jwks_json()
+    if jwks_data is None:
+        jwks_data = await get_jwks_json_default()
+    key_set = KeySet.import_key_set(jwks_data)
+    return key_set
+
+
+@cached(ttl=60 * 60)
+async def validate_token(token_string: str):
+    """Validates the Entra ID access/id token. Returns a user object."""
+    logger.debug(f"Validating token: {token_string}")
+    if token_string.lower().startswith("error"):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail=f"Auth error with Entra ID token: {token_string} See https://learn.microsoft.com/en-us/office/dev/add-ins/develop/troubleshoot-sso-in-office-add-ins#causes-and-handling-of-errors-from-getaccesstoken",
+        )
+    if token_string.lower().startswith("bearer"):
+        parts = token_string.split()
+        if len(parts) != 2:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Auth error: Invalid token, must be in format 'Bearer xxxx'",
+            )
+        token_string = parts[1]
+    else:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Auth error: Invalid token, must be in format 'Bearer xxxx'",
+        )
+    key_set = await get_key_set()
+    try:
+        token = jwt.decode(token_string, key_set)
+    except Exception:
+        logger.exception("Auth error: Failed to decode token")
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Auth error: Failed to decode token",
+        )
+    token_version = token.claims.get("ver")
+    # https://learn.microsoft.com/en-us/azure/active-directory/develop/access-tokens#token-formats
+    # Upgrade to 2.0:
+    # https://learn.microsoft.com/en-us/answers/questions/639834/how-to-get-access-token-version-20.html
+    if token_version == "1.0":
+        issuer = f"https://sts.windows.net/{settings.auth_entraid_tenant_id}/"
+        audience = f"api://{settings.auth_entraid_client_id}"
+    elif token_version == "2.0":
+        issuer = (
+            f"https://login.microsoftonline.com/{settings.auth_entraid_tenant_id}/v2.0"
+        )
+        audience = settings.auth_entraid_client_id
+    else:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail=f"Auth error: Unsupported token version: {token_version}",
+        )
+    try:
+        if not settings.auth_entraid_multitenant:
+            claims_requests = JWTClaimsRegistry(
+                aud={"essential": True, "value": audience},
+                iss={"essential": True, "value": issuer},
+            )
+            claims_requests.validate(token.claims)
+        else:
+            claims_requests = JWTClaimsRegistry(
+                aud={"essential": True, "value": audience},
+            )
+            claims_requests.validate(token.claims)
+            # External users have their own tenant_id
+            issuer_regex = r"https://login\.microsoftonline\.com/(common|organizations|consumers|[0-9a-fA-F-]{36})/v2\.0"
+            if not re.match(issuer_regex, issuer):
+                logger.debug(f"Couldn't match issuer for token: {token_string}")
+                raise HTTPException(
+                    status_code=status.HTTP_401_UNAUTHORIZED,
+                    detail="Auth error: Couldn't validate token",
+                )
+        logger.debug(claims_requests)
+    except Exception as e:
+        logger.debug(f"Authentication error for token: {token_string}")
+        logger.info(repr(e))
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Auth error: Couldn't validate token",
+        )
+
+    current_user = models.User(claims=token.claims)
+    logger.info(f"User authenticated: {current_user.name}")
+    return current_user

xlwings_server/auth/entraid/jwks.py

@@ -0,0 +1,10 @@
+from aiocache import cached
+
+
+@cached(ttl=60 * 60 * 24)
+async def get_jwks_json():
+    """If your application runs on an air-gapped server and can't download the
+    Azure JSON Web Key Set (JWKS), you can provide your own function here to access
+    the JSON file.
+    """
+    pass

xlwings_server/azure_functions_templates/.funcignore

@@ -0,0 +1,28 @@
+# Virtual environments
+.venv/
+venv/
+
+# Secrets & certificates
+.env
+certs/
+*.pem
+*.key
+
+# Git
+.git/
+.gitignore
+
+# Python artifacts
+__pycache__/
+*.pyc
+
+# Local dev settings
+local.settings.json
+
+# IDE
+.vscode/
+.idea/
+
+# Misc
+*.md
+.DS_Store

xlwings_server/azure_functions_templates/function_app.py

@@ -0,0 +1,28 @@
+"""
+Azure Functions
+
+Note: Azure Functions don't support streaming functions/socket.io.
+
+The other files required for Azure Functions are:
+- host.json
+- local.settings.json
+- .funcignore
+
+The function is always called http_app_func, see:
+https://github.com/Azure-Samples/fastapi-on-azure-functions/issues/31
+
+For app logs, in Azure portal go to:
+Function App > My Function App. Than, under `http_app_func`, click on `Invocations and more`.
+"""
+
+import os
+from pathlib import Path
+
+import azure.functions as func
+
+# Must come before importing xlwings_server
+os.environ["XLWINGS_PROJECT_DIR"] = str(Path(__file__).parent)
+
+from xlwings_server.main import main_app  # noqa: E402
+
+app = func.AsgiFunctionApp(app=main_app, http_auth_level=func.AuthLevel.ANONYMOUS)

xlwings_server/azure_functions_templates/host.json

@@ -0,0 +1,22 @@
+{
+  "version": "2.0",
+  "logging": {
+    "applicationInsights": {
+      "samplingSettings": {
+        "isEnabled": true,
+        "excludedTypes": "Request"
+      }
+    }
+  },
+  "extensionBundle": {
+    "id": "Microsoft.Azure.Functions.ExtensionBundle",
+    "version": "[4.*, 5.0.0)"
+  },
+  "extensions":
+  {
+    "http":
+    {
+        "routePrefix": ""
+    }
+  }
+}

xlwings_server/azure_functions_templates/local.settings.json

@@ -0,0 +1,8 @@
+{
+  "IsEncrypted": false,
+  "Values": {
+    "AzureWebJobsStorage": "",
+    "FUNCTIONS_WORKER_RUNTIME": "python",
+    "AzureWebJobsFeatureFlags": "EnableWorkerIndexing"
+  }
+}

xlwings_server/build_utils/__init__.py

@@ -0,0 +1,9 @@
+"""Build-time utilities for xlwings Server.
+
+This package contains tools used during build and deployment processes,
+such as static file hashing for cache-busting.
+"""
+
+from .static_file_hasher import StaticFileHasher
+
+__all__ = ["StaticFileHasher"]

xlwings_server/build_utils/static_file_hasher.py

@@ -0,0 +1,212 @@
+"""Static file hasher for cache-busting in production builds.
+
+This module provides the StaticFileHasher class which adds content-based hashes
+to static file names (e.g., main.js -> main.a1b2c3d4.js) and updates all references
+in HTML, JS, and CSS files accordingly. This is primarily used during the Wasm
+build process to enable effective cache-busting in production deployments.
+"""
+
+import hashlib
+import os
+import re
+from pathlib import Path
+
+
+class StaticFileHasher:
+    """Hashes static files and updates references for cache-busting.
+
+    This utility is used during the Wasm build process to add content-based
+    hashes to static file names (e.g., main.js -> main.a1b2c3d4.js) and update
+    all references in HTML, JS, and CSS files accordingly.
+
+    Args:
+        static_dir: Directory containing static files to hash
+        templates_dir: Directory containing templates with references to update
+    """
+
+    def __init__(self, static_dir: Path, templates_dir: Path):
+        self.static_dir = static_dir
+        self.templates_dir = templates_dir
+        self.file_mapping: dict[
+            str, dict[str, str]
+        ] = {}  # rel_path -> {old_name: new_name, path: Path}
+        self.processed_files: set[Path] = set()
+
+    def get_relative_path(self, path: Path, base_dir: Path) -> Path:
+        """Get the relative path from base_dir to the given path"""
+        try:
+            return path.relative_to(base_dir)
+        except ValueError:
+            return path
+
+    def should_process_file(self, path: Path) -> bool:
+        """Determine if a file should be processed based on various criteria"""
+        if not path.is_file() or path.name.startswith("."):
+            return False
+
+        excluded_patterns = {
+            ".map",
+            ".md",
+            ".py",
+            ".scss",
+            ".txt",
+            ".whl",
+            ".xml",
+            "custom-functions-code.js",
+            "custom-functions-meta.json",
+            "eula.html",
+            "fonts/",
+            "images/ribbon/",
+            "index.html",
+            "manifest.xml",
+            "privacy.html",
+            "support.html",
+            "taskpane.html",
+            "vendor/",
+        }
+
+        path_str = str(path)
+        return (
+            "." in path.name  # requires extension
+            and not any(pattern in path_str for pattern in excluded_patterns)
+        )
+
+    def hash_file(self, path: Path) -> str:
+        """Generate a hash for the given file"""
+        contents = path.read_bytes()
+        return hashlib.sha256(contents).hexdigest()[:8]
+
+    def generate_new_name(self, filename: str, digest: str) -> str:
+        """Generate the new filename with hash included"""
+        name, ext = os.path.splitext(filename)
+        return f"{name}.{digest}{ext}"
+
+    def get_replacement_patterns(
+        self, file_path: Path, rel_path: str, old_name: str, new_name: str
+    ) -> list[tuple[str, str]]:
+        """Generate all possible path patterns for replacement"""
+        patterns = []
+        dir_path = os.path.dirname(rel_path)
+
+        # For absolute paths (mainly HTML references)
+        abs_patterns = [
+            (f"{rel_path}", f"{dir_path}/{new_name}"),
+            (f"/{rel_path}", f"/{dir_path}/{new_name}"),
+        ]
+
+        # For relative paths (mainly JS imports)
+        try:
+            current_dir = file_path.parent.relative_to(self.static_dir)
+            target_dir = Path(dir_path)
+            rel_import_path = os.path.relpath(target_dir, current_dir)
+
+            # Handle the case where files are in the same directory
+            if rel_import_path == ".":
+                rel_patterns = [
+                    (f"./{old_name}", f"./{new_name}"),
+                    (old_name, new_name),
+                ]
+            else:
+                rel_import_path = rel_import_path.replace("\\", "/")
+                if not rel_import_path.startswith("."):
+                    rel_import_path = f"./{rel_import_path}"
+                rel_patterns = [
+                    (f"{rel_import_path}/{old_name}", f"{rel_import_path}/{new_name}"),
+                ]
+        except ValueError:
+            rel_patterns = []
+
+        # Combine all patterns
+        all_paths = abs_patterns + rel_patterns
+
+        # Generate variations for each pattern
+        for old_path, new_path in all_paths:
+            # Normalize slashes
+            old_path = old_path.replace("\\", "/")
+            new_path = new_path.replace("\\", "/")
+
+            # Remove any double slashes
+            old_path = re.sub(r"/{2,}", "/", old_path)
+            new_path = re.sub(r"/{2,}", "/", new_path)
+
+            variations = [
+                (old_path, new_path),
+                (f"'{old_path}'", f"'{new_path}'"),
+                (f'"{old_path}"', f'"{new_path}"'),
+                (f'from "{old_path}"', f'from "{new_path}"'),
+                (f"from '{old_path}'", f"from '{new_path}'"),
+                (f'import "{old_path}"', f'import "{new_path}"'),
+                (f"import '{old_path}'", f"import '{new_path}'"),
+                (f"url({old_path})", f"url({new_path})"),
+                (f'url("{old_path}")', f'url("{new_path}")'),
+                (f"url('{old_path}')", f"url('{new_path}')"),
+            ]
+            patterns.extend(variations)
+
+        return patterns
+
+    def replace_in_file(
+        self, file_path: Path, excluded_dirs: list[str] | None = None
+    ) -> None:
+        """Replace all occurrences of original filenames with hashed versions"""
+        if excluded_dirs is None:
+            excluded_dirs = []
+
+        if any(excluded_dir in file_path.parts for excluded_dir in excluded_dirs):
+            return
+
+        content = file_path.read_text()
+        new_content = content
+
+        # Sort paths by length (longest first) to avoid partial replacements
+        sorted_paths = sorted(self.file_mapping.keys(), key=len, reverse=True)
+
+        for rel_path in sorted_paths:
+            file_info = self.file_mapping[rel_path]
+            old_name = file_info["old_name"]
+            new_name = file_info["new_name"]
+
+            patterns = self.get_replacement_patterns(
+                file_path, rel_path, old_name, new_name
+            )
+
+            for old_pattern, new_pattern in patterns:
+                new_content = new_content.replace(old_pattern, new_pattern)
+
+        if new_content != content:
+            file_path.write_text(new_content)
+
+    def process_files(self):
+        """Process all static files and update references"""
+        # First pass: hash all files and create mapping
+        for source_path in self.static_dir.rglob("*"):
+            if self.should_process_file(source_path):
+                rel_path = self.get_relative_path(source_path, self.static_dir)
+                rel_path_str = str(rel_path).replace("\\", "/")
+
+                digest = self.hash_file(source_path)
+                old_name = source_path.name
+                new_name = self.generate_new_name(old_name, digest)
+
+                self.file_mapping[rel_path_str] = {
+                    "old_name": old_name,
+                    "new_name": new_name,
+                    "path": source_path,
+                }
+
+        # Second pass: rename files
+        for file_info in self.file_mapping.values():
+            old_path = file_info["path"]
+            if old_path.exists():  # Check if not already renamed
+                new_path = old_path.with_name(file_info["new_name"])
+                old_path.rename(new_path)
+
+        # Third pass: update references in files
+        for template_file in self.templates_dir.rglob("*.html"):
+            self.replace_in_file(template_file)
+
+        for js_file in self.static_dir.rglob("*.js"):
+            self.replace_in_file(js_file, excluded_dirs=["vendor"])
+
+        for css_file in self.static_dir.rglob("*.css"):
+            self.replace_in_file(css_file, excluded_dirs=["vendor"])