bugyo-fs 1.0.1

Filesystem plugin for Daimyo - provides filesystem and system context for templates

bugyo-fs

Filesystem plugin for Daimyo - provides filesystem and system context, filters, and tests for Jinja2 templates.

Installation

pip install bugyo-fs

Features

Context Variables

The fs.context plugin provides the following template variables:

Variable	Type	Description
cwd	str	Current working directory (absolute path)
project_root	str	Project root directory (same as cwd)
path_separator	str	OS-specific path separator (/ or \)
is_windows	bool	True if running on Windows
is_linux	bool	True if running on Linux
is_macos	bool	True if running on macOS
hostname	str	System hostname

Filters

The fs.filters plugin provides the following Jinja2 filters:

Filter	Description	Example
basename	Get filename from path	"path/file.txt" | basename → "file.txt"
dirname	Get directory from path	"path/file.txt" | dirname → "path"
relpath	Get relative path	"/abs/path" | relpath("/abs") → "path"
joinpath	Join path components	"dir" | joinpath("file.txt") → "dir/file.txt"
normpath	Normalize path	"./path//file.txt" | normpath → "path/file.txt"

Tests

The fs.filters plugin provides the following Jinja2 tests:

Test	Description	Example
file_exists	Check if file exists	"file.txt" is file_exists
path_exists	Check if path exists	"dir" is path_exists
is_directory	Check if path is directory	"dir" is is_directory
is_file	Check if path is file	"file.txt" is is_file
is_relative	Check if path is relative	"./file.txt" is is_relative

Usage

Configuration

Enable the plugin in your .daimyo/config/settings.toml:

# Enable all filesystem plugins
enabled_plugins = ["fs.*"]

# Or enable specific plugins
enabled_plugins = ["fs.context", "fs.filters"]

Template Examples

Platform-Specific Rules

In your YAML rule files:

python.general:
  when: Python development guidelines
  ruleset:
    - "{% if is_linux %}Use forward slashes in paths{% endif %}"
    - "{% if is_linux %}Package manager: apt/dnf{% endif %}"
    - "{% if is_windows %}Use backslashes in paths{% endif %}"
    - "{% if is_windows %}Package manager: winget/choco{% endif %}"
    - "{% if is_macos %}Use forward slashes in paths{% endif %}"
    - "{% if is_macos %}Package manager: brew{% endif %}"

Conditional Rules Based on File Existence

project.setup:
  when: Project setup guidelines
  ruleset:
    - "{% if 'pyproject.toml' is file_exists %}This is a Python project using pyproject.toml{% endif %}"
    - "{% if 'pyproject.toml' is file_exists %}Use uv or pip for dependency management{% endif %}"
    - "{% if 'package.json' is file_exists %}This is a Node.js project{% endif %}"
    - "{% if 'package.json' is file_exists %}Use npm or yarn for dependency management{% endif %}"
    - "{% if '.git' is is_directory %}This project uses Git for version control{% endif %}"
    - "{% if '.git' is is_directory %}Remember to commit your changes regularly{% endif %}"

Path Manipulation

project.info:
  when: Project information
  ruleset:
    - "Working directory: {{ cwd }}"
    - "Project: {{ cwd | basename }}"
    - "{% set config_file = 'config' | joinpath('settings.toml') %}Configuration file: {{ config_file }}"
    - "{% set config_file = 'config' | joinpath('settings.toml') %}{% if config_file is file_exists %}Config file found at {{ config_file }}{% else %}Config file not found - using defaults{% endif %}"

System Information

system.info:
  when: System information
  ruleset:
    - "Hostname: {{ hostname }}"
    - "Path separator: {{ path_separator }}"
    - "{% if is_linux %}Platform: Linux{% endif %}"

Security

Important: This plugin implements strict path validation to prevent security vulnerabilities.

Path Traversal Protection

All path operations are validated to ensure they stay within the current working directory. This prevents malicious templates from accessing sensitive system files.

Blocked Operations

The following path operations will raise ValueError:

# Parent directory traversal
"../../../etc/passwd"           # Blocked

# Absolute paths outside cwd
"/etc/passwd"                   # Blocked
"/home/user/.ssh/id_rsa"       # Blocked

# Symlinks pointing outside cwd
"escape_link" → "/etc/passwd"   # Blocked

Allowed Operations

Only paths within the current working directory are allowed:

# Relative paths within cwd
"file.txt"                      # Allowed
"./file.txt"                    # Allowed
"subdir/file.txt"              # Allowed

# Absolute paths within cwd
"/path/to/project/file.txt"     # Allowed (if cwd is /path/to/project)

Security Features

• No home directory access: home_dir and temp_dir are not exposed
• No abspath filter: Prevents revealing system paths
• No expanduser filter: Prevents accessing home directory
• No is_readable/is_writable tests: Reduces attack surface
• Safe error handling: Tests return False instead of raising errors for invalid paths

Error Messages

Path traversal attempts will raise descriptive errors:

ValueError: Path traversal attempt detected: '../../../etc/passwd' resolves
outside current working directory. Only paths within /path/to/project are allowed.

Limitations

• Scope: Only the current working directory and its subdirectories are accessible
• Symlinks: Symlinks pointing outside cwd are rejected
• Absolute paths: Only absolute paths within cwd are allowed
• Parent directories: Cannot access parent directories of cwd

These limitations are intentional security features to prevent malicious template code from accessing sensitive files.

Requirements

• Python >= 3.11
• daimyo >= 1.4.0

Standard library only (no additional dependencies).

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please ensure:

1. All tests pass
2. Security constraints are maintained
3. Code passes mypy and ruff checks
4. Documentation is updated

Support

For issues and questions, please visit the Daimyo issue tracker.