safe-fs-tools

safe-fs-tools is a Rust library and CLI for policy-bounded filesystem operations.

It provides read, list_dir, glob, grep, stat, edit, patch, mkdir, write, move, copy_file, and delete with explicit root boundaries, permission gates, deny rules, and resource limits.

• Library operation names use snake_case (list_dir, copy_file).
• CLI subcommands use kebab-case (list-dir, copy-file).

MSRV: Rust 1.92.0.

Why This Exists

The core objective is explicit safety contracts for local file tooling:

• SandboxPolicy: what is allowed.
• Root: where access is anchored.
• SecretRules: what must be denied or redacted.
• Limits: how much work is allowed.
• metadata.policy_meta: optional shared/descriptive metadata, not an enforcement switch in safe-fs-tools.

This project is not an OS sandbox. See SECURITY.md and docs/security-guide.md.

Documentation

For full documentation (Next.js-docs style structure), start here:

• docs/index.md (full portal)
• docs/getting-started.md
• docs/concepts.md
• docs/policy-reference.md
• docs/operations-reference.md
• docs/cli-reference.md
• docs/library-reference.md
• docs/security-guide.md
• docs/deployment-and-ops.md
• docs/faq.md
• docs/db-vfs.md

Quick Start (CLI)

1. Copy and edit a policy:

cp policy.example.toml ./policy.toml
# then replace <ABSOLUTE_PATH> with a real absolute path

2. Run help:

cargo run -p safe-fs-tools-cli -- --policy ./policy.toml --help

3. Read a file:

cargo run -p safe-fs-tools-cli -- \
  --policy ./policy.toml \
  read --root workspace README.md

Quick Start (Library)

use safe_fs_tools::{Context, ReadRequest, RootMode, SandboxPolicy};

let mut policy =
    SandboxPolicy::single_root("workspace", "/abs/path/to/workspace", RootMode::ReadOnly);
policy.permissions.read = true;

let ctx = Context::new(policy)?;
let resp = ctx.read_file(ReadRequest {
    root_id: "workspace".to_string(),
    path: "README.md".into(),
    start_line: None,
    end_line: None,
})?;

println!("{}", resp.content);
# Ok::<(), safe_fs_tools::Error>(())

SandboxPolicy can also carry optional [metadata.policy_meta] fields for cross-tool policy annotations. In safe-fs-tools they are descriptive only and do not override [[roots]].write_scope, permissions, or limits.

Cargo Features

• Default: glob, grep, patch
• Optional: policy-io

If a feature is disabled, the operation API remains available but returns Error::NotPermitted.

Development

cargo fmt --all -- --check
cargo check --workspace --all-targets
cargo check -p safe-fs-tools --all-targets --no-default-features
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
./scripts/gate.sh

Enable hooks once per clone:

git config core.hooksPath githooks