| 1 | # rfc_files.py DOX |
| 2 | |
| 3 | ## Purpose |
| 4 | |
| 5 | - Own the `rfc_files.py` helper module. |
| 6 | - This module exposes RFC-safe filesystem operations. |
| 7 | - Keep this file-level DOX profile synchronized with `rfc_files.py` because this directory is intentionally flat. |
| 8 | |
| 9 | ## Ownership |
| 10 | |
| 11 | - `rfc_files.py` owns the runtime implementation. |
| 12 | - `rfc_files.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. |
| 13 | - Top-level functions: |
| 14 | - `get_abs_path(*relative_paths)`: Convert relative paths to absolute paths based on the base directory. |
| 15 | - `read_file_bin(relative_path: str, backup_dirs=...) -> bytes`: Read binary file content. |
| 16 | - `read_file_base64(relative_path: str, backup_dirs=...) -> str`: Read file content and return as base64 string. |
| 17 | - `write_file_binary(relative_path: str, content: bytes) -> bool`: Write binary content to a file. |
| 18 | - `write_file_base64(relative_path: str, content: str) -> bool`: Write base64 content to a file. |
| 19 | - `delete_file(relative_path: str) -> bool`: Delete a file. |
| 20 | - `delete_directory(relative_path: str) -> bool`: Delete a directory recursively. |
| 21 | - `list_directory(relative_path: str, include_hidden: bool=...) -> list`: List directory contents. |
| 22 | - `make_directories(relative_path: str) -> bool`: Create directories recursively. |
| 23 | - `path_exists(relative_path: str) -> bool`: Check if a path exists. |
| 24 | - `file_exists(relative_path: str) -> bool`: Check if a file exists. |
| 25 | - `folder_exists(relative_path: str) -> bool`: Check if a folder exists. |
| 26 | - `get_subdirectories(relative_path: str, include: str | list[str]=..., exclude: str | list[str] | None=...) -> list[str]`: Get subdirectories in a directory. |
| 27 | - `zip_directory(relative_path: str) -> str`: Create a zip archive of a directory. |
| 28 | - `move_file(source_path: str, destination_path: str) -> bool`: Move a file from source to destination. |
| 29 | - `read_directory_as_zip(relative_path: str) -> bytes`: Read entire directory contents as a zip file. |
| 30 | - `find_file_in_dirs(file_path: str, backup_dirs: list[str]) -> str`: Find a file in the main directory or backup directories. |
| 31 | - `_read_file_binary_impl(file_path: str) -> str`: Implementation function to read a file in binary mode. |
| 32 | - `_write_file_binary_impl(file_path: str, b64_content: str) -> bool`: Implementation function to write binary content to a file. |
| 33 | - `_delete_file_impl(file_path: str) -> bool`: Implementation function to delete a file. |
| 34 | - `_delete_folder_impl(folder_path: str) -> bool`: Implementation function to delete a folder recursively. |
| 35 | - `_list_folder_impl(folder_path: str, include_hidden: bool=...) -> list`: Implementation function to list folder contents. |
| 36 | - `_make_dirs_impl(folder_path: str) -> bool`: Implementation function to create directories. |
| 37 | - `_path_exists_impl(file_path: str) -> bool`: Implementation function to check if path exists. |
| 38 | - `_file_exists_impl(file_path: str) -> bool`: Implementation function to check if file exists. |
| 39 | - `_folder_exists_impl(folder_path: str) -> bool`: Implementation function to check if folder exists. |
| 40 | - `_get_subdirectories_impl(folder_path: str, include: str | list[str], exclude: str | list[str] | None) -> list[str]`: Implementation function to get subdirectories. |
| 41 | - `_zip_dir_impl(folder_path: str) -> str`: Implementation function to create a zip archive of a directory. |
| 42 | - `_move_file_impl(source_path: str, destination_path: str) -> bool`: Implementation function to move a file. |
| 43 | - `_read_directory_impl(dir_path: str) -> str`: Implementation function to zip a directory and return base64 encoded zip. |
| 44 | |
| 45 | ## Runtime Contracts |
| 46 | |
| 47 | - Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. |
| 48 | - Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. |
| 49 | - Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion. |
| 50 | - Imported dependency areas include: `base64`, `fnmatch`, `helpers`, `os`, `shutil`, `tempfile`, `zipfile`. |
| 51 | |
| 52 | ## Key Concepts |
| 53 | |
| 54 | - Important called helpers/classes observed in the source: `os.path.abspath`, `os.path.join`, `find_file_in_dirs`, `runtime.call_development_function_sync`, `base64.b64decode`, `get_abs_path`, `base64.b64encode.decode`, `FileNotFoundError`, `os.path.exists`, `os.path.basename`, `os.path.isfile`, `Exception`, `os.makedirs`, `os.remove`, `os.path.isdir`, `shutil.rmtree`, `os.listdir`, `items.sort`, `tempfile.NamedTemporaryFile`, `zipfile.ZipFile`. |
| 55 | - Keep request/response, tool, or helper semantics documented here at the same time as source changes. |
| 56 | |
| 57 | ## Work Guidance |
| 58 | |
| 59 | - Preserve public helper APIs used by core code and plugins unless every caller is updated. |
| 60 | - Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. |
| 61 | - Prefer adding cohesive helper functions here only when behavior is reused across modules. |
| 62 | |
| 63 | ## Verification |
| 64 | |
| 65 | - Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. |
| 66 | - No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check. |
| 67 | |
| 68 | ## Child DOX Index |
| 69 | |
| 70 | No child DOX files. |