fs_append_text()

def fs_append_text(path, content) -> NoneType

Append text content to the end of a file.

If the file does not exist, it will be created. This is useful for building up log files or accumulating data.

Raises: Error: If the file cannot be created or written

Args

• path: string: Path to the file (relative to workspace root)
• content: string: Text content to append

Returns

None

fs_chmod()

def fs_chmod(path, spec) -> NoneType

Change file permissions using symbolic notation (Unix-like).

Supports specification like “u+rx”, “g-w”, “a=r”, etc. Only available on Unix-like systems.

Raises: Error: If spec is invalid or permissions cannot be set

Args

• path: string: Path to the file (relative to workspace root)
• spec: string: Chmod specification as string ([ugoa][+-=][rwx]+), e.g., “u+x”, “u+rx”, “a-w”

Returns

None

fs_chown()

def fs_chown(path, user, group) -> NoneType

Change file ownership (Unix-like systems only).

Raises: Error: If user/group don’t exist or chown fails

Args

• path: string: Path to the file (relative to workspace root)
• user: string: Username to set as owner
• group: string: Group name to set as group owner

Returns

None

fs_copy()

def fs_copy(src, dst, recursive, overwrite, follow_symlinks) -> NoneType

Copy a file or directory to a destination.

Raises: Error: If source is directory but recursive=False, or if copy fails

Args

• src: string: Source path (file or directory)
• dst: string: Destination path
• recursive: bool: If True, recursively copy directories (required for directories)
• overwrite: bool: If True, overwrite destination if it exists
• follow_symlinks: bool: If True, follow symlinks; if False, copy the link itself

Returns

None

fs_exists()

def fs_exists(path) -> bool

Check if a file or directory exists.

Args

• path: string: Path to check (relative to workspace root)

Returns

bool: True if the path exists, False otherwise

fs_is_directory()

def fs_is_directory(path) -> bool

Check if a path is a directory.

Args

• path: string: Path to check (relative to workspace root)

Returns

bool: True if the path is a directory, False otherwise

fs_is_file()

def fs_is_file(path) -> bool

Check if a path is a regular file.

Args

• path: string: Path to check (relative to workspace root)

Returns

bool: True if the path is a regular file, False otherwise

fs_is_symlink()

def fs_is_symlink(path) -> bool

Check if a path is a symbolic link.

Args

• path: string: Path to check (relative to workspace root)

Returns

bool: True if the path is a symbolic link, False otherwise

fs_is_text_file()

def fs_is_text_file(path) -> bool

Check if a file is a text file (vs binary).

Raises: Error: If the path is not a file or cannot be read

Args

• path: string: Path to the file (relative to workspace root)

Returns

bool: True if the file appears to be text, False if binary

fs_metadata()

def fs_metadata(path) -> dict

Get metadata about a file or directory.

Returns a dictionary with file information including size, timestamps, type, and permissions.

Raises: Error: If the path cannot be accessed

Args

• path: string: Path to the file or directory (relative to workspace root)

Returns

dict: Dictionary with keys: - size: File size in bytes (int) - modified: Last modification time as seconds since epoch (float) - created: Creation time as seconds since epoch (float or None) - is_dir: Whether it’s a directory (bool) - is_file: Whether it’s a regular file (bool) - is_symlink: Whether it’s a symbolic link (bool) - permissions: Human-readable permissions string (str, e.g., “rw-r–r–”) - mode: Numeric permissions in octal (int)

fs_mkdir()

def fs_mkdir(path, parents, exist_ok) -> NoneType

Create a directory.

Raises: Error: If the directory cannot be created

Args

• path: string: Path to the directory to create (relative to workspace root)
• parents: bool: If True, create parent directories as needed (like mkdir -p)
• exist_ok: bool: If True, don’t error if directory already exists

Returns

None

fs_modified()

def fs_modified(path) -> float

Get the modification time of a file.

Raises: Error: If the file cannot be accessed

Args

• path: string: Path to the file (relative to workspace root)

Returns

float: Modification time as seconds since Unix epoch (January 1, 1970)

fs_move()

def fs_move(src, dst, overwrite) -> NoneType

Move or rename a file or directory.

Creates parent directories for the destination if needed.

Raises: Error: If destination exists and overwrite=False, or if move fails

Args

• src: string: Source path
• dst: string: Destination path
• overwrite: bool: If True, overwrite destination if it exists

Returns

None

fs_read_bytes()

def fs_read_bytes(path) -> list

Read a file as a list of byte values (0-255).

Raises: Error: If the file cannot be read

Args

• path: string: Path to the file (relative to workspace root)

Returns

list: List of integers representing bytes (0-255)

fs_read_directory()

def fs_read_directory(path) -> list

List the contents of a directory.

Returns a list of full paths to entries in the directory. The list is not sorted and includes both files and subdirectories.

Raises: Error: If the directory cannot be read or does not exist

Args

• path: string: Path to the directory (relative to workspace root)

Returns

list: List of full paths to directory entries

fs_read_json()

def fs_read_json(path) -> dict

Read and parse a JSON file into a dictionary.

Raises: Error: If the file cannot be read or is not valid JSON

Args

• path: string: Path to the JSON file (relative to workspace root)

Returns

dict: Parsed JSON data as a Starlark dictionary

fs_read_lines()

def fs_read_lines(path) -> list

Read a text file as a list of lines (newlines stripped).

Raises: Error: If the file cannot be read

Args

• path: string: Path to the text file (relative to workspace root)

Returns

list: List of strings, one per line (without newline characters)

fs_read_link()

def fs_read_link(path) -> string

Read the target of a symbolic link.

Raises: Error: If the path is not a symlink or cannot be read

Args

• path: string: Path to the symbolic link (relative to workspace root)

Returns

str: The target path that the symlink points to

fs_read_text()

def fs_read_text(path) -> string

Read the entire contents of a text file.

Raises: Error: If the file cannot be read or does not exist

Args

• path: string: Path to the text file (relative to workspace root)

Returns

str: The complete file contents as a string

fs_read_toml()

def fs_read_toml(path) -> dict

Read and parse a TOML file into a dictionary.

Raises: Error: If the file cannot be read or is not valid TOML

Args

• path: string: Path to the TOML file (relative to workspace root)

Returns

dict: Parsed TOML data as a Starlark dictionary

fs_read_yaml()

def fs_read_yaml(path) -> dict

Read and parse a YAML file into a dictionary.

Raises: Error: If the file cannot be read or is not valid YAML

Args

• path: string: Path to the YAML file (relative to workspace root)

Returns

dict: Parsed YAML data as a Starlark dictionary

fs_remove()

def fs_remove(path, recursive, missing_ok) -> NoneType

Remove a file or directory.

Raises: Error: If path doesn’t exist and missing_ok=False, or if removal fails

Args

• path: string: Path to remove (relative to workspace root)
• recursive: bool: If True, recursively remove directories and contents
• missing_ok: bool: If True, don’t error if path doesn’t exist

Returns

None

fs_set_permissions()

def fs_set_permissions(path, mode) -> NoneType

Set file permissions using numeric mode (Unix octal notation).

Raises: Error: If permissions cannot be set (may not be supported on all OS)

Args

• path: string: Path to the file (relative to workspace root)
• mode: int: Numeric permissions in octal (e.g., 0o644, 0o755, 0o600)

Returns

None

fs_size()

def fs_size(path) -> int

Get the size of a file in bytes.

Raises: Error: If the file cannot be accessed

Args

• path: string: Path to the file (relative to workspace root)

Returns

int: File size in bytes

fs_symlink()

def fs_symlink(target, link) -> NoneType

Create a symbolic link.

Creates a symlink at link that points to target.

Raises: Error: If the symlink cannot be created

Args

• target: string: The target path that the symlink points to
• link: string: The symlink path to create (relative to workspace root)

Returns

None

fs_touch()

def fs_touch(path, create, update_mtime) -> NoneType

Update file modification time or create an empty file.

Raises: Error: If file cannot be created or modified

Args

• path: string: Path to the file (relative to workspace root)
• create: bool: If True, create file if it doesn’t exist
• update_mtime: bool: If True, update modification time to now

Returns

None

fs_write_bytes()

def fs_write_bytes(path, data) -> NoneType

Write a list of byte values to a file.

Raises: Error: If bytes are out of range or file cannot be written

Args

• path: string: Path to the file (relative to workspace root)
• data: list: List of integers (0-255) representing bytes

Returns

None

fs_write_json()

def fs_write_json(path, data, pretty) -> NoneType

Write a dictionary to a JSON file.

Raises: Error: If the data cannot be serialized or file cannot be written

Args

• path: string: Path to the JSON file (relative to workspace root)
• data: dict: Dictionary or list to serialize
• pretty: bool: If True (default), write formatted JSON with indentation

Returns

None

fs_write_lines()

def fs_write_lines(path, lines) -> NoneType

Write a list of strings as lines to a file.

Lines are joined with newline characters. Each string in the list becomes one line in the output file.

Raises: Error: If the file cannot be written

Args

• path: string: Path to the file (relative to workspace root)
• lines: list: List of strings to write

Returns

None

fs_write_string_atomic()

def fs_write_string_atomic(path, content, mode) -> NoneType

Atomically write text to a file with proper permissions.

This function writes to a temporary file first, then atomically renames it to the destination. This ensures the file is never left in a partial or corrupt state. Useful for configuration files or critical data.

Raises: Error: If the file cannot be written or permissions cannot be set

Args

• path: string: Path to the file (relative to workspace root)
• content: string: Text content to write
• mode: int: Unix file permissions as octal number (default: 0o644)

Returns

None

fs_write_text()

def fs_write_text(path, content) -> NoneType

Write text content to a file, overwriting if it exists.

Creates parent directories if they don’t exist. If the file already exists, its contents will be completely replaced.

Raises: Error: If the file cannot be created or written

Args

• path: string: Path to the file (relative to workspace root)
• content: string: Text content to write

Returns

None

fs_write_toml()

def fs_write_toml(path, data) -> NoneType

Write a dictionary to a TOML file.

Raises: Error: If the data cannot be serialized or file cannot be written

Args

• path: string: Path to the TOML file (relative to workspace root)
• data: dict: Dictionary to serialize as TOML

Returns

None

fs_write_yaml()

def fs_write_yaml(path, data) -> NoneType

Write a dictionary to a YAML file.

Raises: Error: If the data cannot be serialized or file cannot be written

Args

• path: string: Path to the YAML file (relative to workspace root)
• data: dict: Dictionary or list to serialize as YAML

Returns

None