runspec-fs-core 0.1.0__tar.gz

runspec_fs_core-0.1.0/.gitignore

@@ -0,0 +1,61 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+.venv/
+venv/
+env/
+.env
+pip-wheel-metadata/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+coverage.xml
+*.cover
+
+# Node
+node_modules/
+dist/
+*.js.map
+.npm
+
+# Go
+*.exe
+*.test
+*.out
+vendor/
+
+# IDE
+.idea/
+.vscode/
+*.iml
+*.iws
+*.ipr
+.DS_Store
+Thumbs.db
+
+# Docs
+site/
+
+# Misc
+*.log
+*.tmp
+
+# External reference repos (cloned locally, not committed)
+chainlit-docs/
+.chainlit/
+
+# Claude Code local config (machine-specific)
+.claude/launch.json
+
+# Stray committed test venv (removed from tracking)
+.venv-test/

runspec_fs_core-0.1.0/CHANGELOG.md

@@ -0,0 +1,35 @@
+# runspec-fs-core Changelog
+
+## [0.1.0] — 2026-07-25
+
+Initial release.
+
+The pure-Python logic core behind `runspec-fs` — a stdlib port of the
+[Filesystem MCP server](https://github.com/modelcontextprotocol/servers/tree/HEAD/src/filesystem)
+tool set. Provides the filesystem helpers as plain importable functions — **no
+dependency on `runspec`, no `runspec.toml`, no console-script entry points** — so
+a package can `from runspec_fs_core import read_text_file` (and the rest) without
+surfacing any runnables in the venv or in `runspec local` / `runspec serve`
+discovery.
+
+Each function returns plain data and *raises* on failure — the stdlib `OSError`
+family (`FileNotFoundError`, `NotADirectoryError`, `PermissionError`,
+`FileExistsError`) for filesystem problems, plus `EditNotAppliedError` when an
+`edit_file` old-text block is not found; the runnable wrappers in `runspec-fs`
+catch these and render the JSON/exit behaviour.
+
+No directory jail is enforced: filesystem access is bounded by the OS permissions
+of the user the process runs as. `allowed_directories()` reports the effective
+user + home/cwd and is informational only.
+
+Exports:
+
+- **Read** — `read_text_file` (head/tail), `read_media_file` (base64 + MIME),
+  `read_multiple_files` (per-file errors)
+- **Write / edit** — `write_file`, `edit_file` (ordered substring replacements,
+  unified diff, `dry_run`)
+- **Directories** — `create_directory`, `list_directory`,
+  `list_directory_with_sizes` (name/size sort), `directory_tree`, `move_file`
+- **Search / info** — `search_files` (glob or substring, exclude globs),
+  `get_file_info`, `allowed_directories`
+- **Errors** — `FsCoreError`, `EditNotAppliedError`

runspec_fs_core-0.1.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: runspec-fs-core
+Version: 0.1.0
+Summary: Pure-Python filesystem helpers — the importable core behind runspec-fs (no runspec dependency, no runnables)
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff==0.15.20; extra == 'dev'

runspec_fs_core-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "runspec-fs-core"
+version = "0.1.0"
+requires-python = ">=3.10"
+description = "Pure-Python filesystem helpers — the importable core behind runspec-fs (no runspec dependency, no runnables)"
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "ruff==0.15.20",
+    "mypy",
+    "pytest>=8.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.10"
+
+[tool.ruff]
+line-length = 200
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]

runspec_fs_core-0.1.0/runspec_fs_core/__init__.py

@@ -0,0 +1,59 @@
+"""runspec-fs-core — pure-Python filesystem helpers.
+
+This package has **no dependency on runspec** and ships **no runspec.toml and no
+entry points**, so installing it exposes the helper functions for import without
+surfacing any runnables (it is invisible to ``runspec local`` / ``runspec serve``
+discovery). ``runspec-fs`` depends on it and wraps each helper as a verb of the
+``fs`` runnable.
+
+The helpers are a stdlib port of the
+`Filesystem MCP server <https://github.com/modelcontextprotocol/servers/tree/HEAD/src/filesystem>`_
+tool set. Each function does the work and returns plain data; failures raise —
+the stdlib ``OSError`` family (``FileNotFoundError``, ``NotADirectoryError``,
+``PermissionError`` …) for filesystem problems, plus
+``runspec_fs_core.errors.EditNotAppliedError`` for a failed ``edit_file``.
+
+No directory jail is enforced: filesystem access is bounded by the OS permissions
+of the user the process runs as. See ``allowed_directories``.
+"""
+
+from runspec_fs_core.dirs import (
+    create_directory,
+    directory_tree,
+    list_directory,
+    list_directory_with_sizes,
+    move_file,
+)
+from runspec_fs_core.errors import EditNotAppliedError, FsCoreError
+from runspec_fs_core.files import (
+    edit_file,
+    read_media_file,
+    read_multiple_files,
+    read_text_file,
+    write_file,
+)
+from runspec_fs_core.info import allowed_directories, get_file_info
+from runspec_fs_core.search import search_files
+
+__all__ = [
+    # errors
+    "FsCoreError",
+    "EditNotAppliedError",
+    # read
+    "read_text_file",
+    "read_media_file",
+    "read_multiple_files",
+    # write / edit
+    "write_file",
+    "edit_file",
+    # directories
+    "create_directory",
+    "list_directory",
+    "list_directory_with_sizes",
+    "directory_tree",
+    "move_file",
+    # search / info
+    "search_files",
+    "get_file_info",
+    "allowed_directories",
+]

runspec_fs_core-0.1.0/runspec_fs_core/dirs.py

@@ -0,0 +1,133 @@
+"""Directory helpers — the pure logic behind the ``fs`` runnable's directory
+verbs (``create-directory``, ``list-directory``, ``list-directory-with-sizes``,
+``directory-tree``, ``move-file``).
+
+Each function takes plain params, returns plain data, and raises on failure
+(stdlib ``OSError`` family: ``FileNotFoundError``, ``NotADirectoryError``,
+``FileExistsError`` …).
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import os
+import shutil
+from pathlib import Path
+from typing import Any
+
+
+def _as_path(path: str | os.PathLike[str]) -> Path:
+    return Path(path).expanduser()
+
+
+def _excluded(name: str, exclude: list[str] | None) -> bool:
+    return bool(exclude) and any(fnmatch.fnmatch(name, pat) for pat in exclude)  # type: ignore[union-attr]
+
+
+def create_directory(path: str | os.PathLike[str]) -> dict[str, Any]:
+    """Create a directory (and any missing parents). Idempotent — confirming an
+    existing directory succeeds. Returns ``{path, created}`` where ``created`` is
+    ``False`` if it already existed."""
+    p = _as_path(path)
+    existed = p.exists()
+    p.mkdir(parents=True, exist_ok=True)
+    return {"path": str(p), "created": not existed}
+
+
+def _entry_type(entry: os.DirEntry[str] | Path) -> str:
+    return "directory" if entry.is_dir() else "file"
+
+
+def list_directory(path: str | os.PathLike[str]) -> dict[str, Any]:
+    """List a directory's immediate contents. Returns
+    ``{path, entries: [{name, type}]}`` sorted directories-first then by name."""
+    p = _as_path(path)
+    entries = [{"name": e.name, "type": _entry_type(e)} for e in sorted(p.iterdir(), key=lambda e: (e.is_file(), e.name.lower()))]
+    return {"path": str(p), "entries": entries, "count": len(entries)}
+
+
+def list_directory_with_sizes(
+    path: str | os.PathLike[str],
+    *,
+    sort_by: str = "name",
+) -> dict[str, Any]:
+    """List a directory's contents with per-entry sizes and aggregate statistics.
+
+    ``sort_by`` is ``"name"`` (default) or ``"size"`` (descending). Returns
+    ``{path, entries: [{name, type, size}], total_files, total_directories,
+    total_size}``.
+    """
+    if sort_by not in ("name", "size"):
+        raise ValueError("sort_by must be 'name' or 'size'")
+    p = _as_path(path)
+
+    entries: list[dict[str, Any]] = []
+    total_files = 0
+    total_dirs = 0
+    total_size = 0
+    for e in p.iterdir():
+        is_dir = e.is_dir()
+        size = 0 if is_dir else e.stat().st_size
+        entries.append({"name": e.name, "type": "directory" if is_dir else "file", "size": size})
+        if is_dir:
+            total_dirs += 1
+        else:
+            total_files += 1
+            total_size += size
+
+    if sort_by == "size":
+        entries.sort(key=lambda x: x["size"], reverse=True)
+    else:
+        entries.sort(key=lambda x: (x["type"] == "file", x["name"].lower()))
+
+    return {
+        "path": str(p),
+        "entries": entries,
+        "total_files": total_files,
+        "total_directories": total_dirs,
+        "total_size": total_size,
+    }
+
+
+def directory_tree(
+    path: str | os.PathLike[str],
+    *,
+    exclude: list[str] | None = None,
+) -> dict[str, Any]:
+    """Return a recursive JSON tree of a directory. Each node is
+    ``{name, type}`` and directories carry a ``children`` list. ``exclude`` is a
+    list of glob patterns matched against entry names at every level."""
+    root = _as_path(path)
+
+    def build(node: Path) -> dict[str, Any]:
+        result: dict[str, Any] = {"name": node.name, "type": "directory"}
+        children: list[dict[str, Any]] = []
+        for child in sorted(node.iterdir(), key=lambda c: (c.is_file(), c.name.lower())):
+            if _excluded(child.name, exclude):
+                continue
+            if child.is_dir():
+                children.append(build(child))
+            else:
+                children.append({"name": child.name, "type": "file"})
+        result["children"] = children
+        return result
+
+    tree = build(root)
+    # The root node's name is the full path so the caller knows what was walked.
+    tree["name"] = str(root)
+    return {"path": str(root), "tree": tree}
+
+
+def move_file(
+    source: str | os.PathLike[str],
+    destination: str | os.PathLike[str],
+) -> dict[str, Any]:
+    """Move or rename a file or directory. Fails if the destination already
+    exists (mirrors the MCP tool — no silent overwrite). Returns
+    ``{source, destination}``."""
+    src = _as_path(source)
+    dst = _as_path(destination)
+    if dst.exists():
+        raise FileExistsError(f"destination already exists: {dst}")
+    shutil.move(str(src), str(dst))
+    return {"source": str(src), "destination": str(dst)}

runspec_fs_core-0.1.0/runspec_fs_core/errors.py

@@ -0,0 +1,19 @@
+"""Exception types raised by the pure helper functions.
+
+The functions in this package do the work and *raise* on failure; the thin
+runnable wrappers in ``runspec-fs`` catch these (alongside the stdlib ``OSError``
+family — ``FileNotFoundError``, ``NotADirectoryError``, ``PermissionError`` …)
+and turn them into the JSON error payloads + non-zero exits that the CLI/agent
+surface expects. The OS errors are left to propagate as themselves rather than
+being re-wrapped, so a wrapper (or a corporate importer) can react to the exact
+failure (missing path vs. permission denied) without parsing a message.
+"""
+
+
+class FsCoreError(Exception):
+    """Base class for all runspec-fs-core failures that aren't a plain OSError."""
+
+
+class EditNotAppliedError(FsCoreError):
+    """An ``edit_file`` old-text block was not found in the file, so the edit
+    could not be applied (nothing is written)."""

runspec_fs_core-0.1.0/runspec_fs_core/files.py

@@ -0,0 +1,144 @@
+"""File read/write/edit helpers — the pure logic behind the ``fs`` runnable's
+file verbs (``read-text-file``, ``read-media-file``, ``read-multiple-files``,
+``write-file``, ``edit-file``).
+
+Each function takes plain params (``str``/``os.PathLike``), returns plain data,
+and raises on failure. Filesystem errors propagate as the stdlib ``OSError``
+family; ``edit_file`` raises :class:`EditNotAppliedError` when an old-text block
+is not present.
+"""
+
+from __future__ import annotations
+
+import base64
+import difflib
+import mimetypes
+import os
+from pathlib import Path
+from typing import Any
+
+from runspec_fs_core.errors import EditNotAppliedError
+
+
+def _as_path(path: str | os.PathLike[str]) -> Path:
+    """Normalise an incoming path. ``expanduser`` only — the ``path``-typed args
+    are already resolved by runspec's coercer, and str-typed paths shouldn't have
+    symlinks silently resolved out from under the caller."""
+    return Path(path).expanduser()
+
+
+def read_text_file(
+    path: str | os.PathLike[str],
+    *,
+    head: int | None = None,
+    tail: int | None = None,
+) -> dict[str, Any]:
+    """Read a file as UTF-8 text.
+
+    ``head``/``tail`` return only the first / last N lines respectively (they are
+    mutually exclusive, mirroring the MCP tool). Returns
+    ``{path, content, truncated}``.
+    """
+    if head is not None and tail is not None:
+        raise ValueError("Pass only one of head / tail, not both")
+    p = _as_path(path)
+    text = p.read_text(encoding="utf-8")
+
+    if head is None and tail is None:
+        return {"path": str(p), "content": text, "truncated": False}
+
+    lines = text.splitlines(keepends=True)
+    if head is not None:
+        if head < 0:
+            raise ValueError("head must be >= 0")
+        selected = lines[:head]
+    else:  # tail is not None
+        if tail < 0:  # type: ignore[operator]
+            raise ValueError("tail must be >= 0")
+        selected = lines[-tail:] if tail else []
+    return {
+        "path": str(p),
+        "content": "".join(selected),
+        "truncated": len(selected) < len(lines),
+    }
+
+
+def read_media_file(path: str | os.PathLike[str]) -> dict[str, Any]:
+    """Read a file's raw bytes and return them base64-encoded with a guessed MIME
+    type. Returns ``{path, mime_type, base64, bytes}``."""
+    p = _as_path(path)
+    data = p.read_bytes()
+    mime, _ = mimetypes.guess_type(str(p))
+    return {
+        "path": str(p),
+        "mime_type": mime or "application/octet-stream",
+        "base64": base64.b64encode(data).decode("ascii"),
+        "bytes": len(data),
+    }
+
+
+def read_multiple_files(paths: list[str | os.PathLike[str]]) -> dict[str, Any]:
+    """Read several files. A failed read is captured per-file rather than aborting
+    the whole batch. Returns ``{files: [{path, content} | {path, error}]}``."""
+    results: list[dict[str, Any]] = []
+    for path in paths:
+        p = _as_path(path)
+        try:
+            results.append({"path": str(p), "content": p.read_text(encoding="utf-8")})
+        except OSError as exc:
+            results.append({"path": str(p), "error": str(exc)})
+        except UnicodeDecodeError:
+            results.append({"path": str(p), "error": "not a UTF-8 text file"})
+    return {"files": results, "count": len(results)}
+
+
+def write_file(path: str | os.PathLike[str], content: str) -> dict[str, Any]:
+    """Create or overwrite a file with UTF-8 text. Returns
+    ``{path, bytes_written}``."""
+    p = _as_path(path)
+    data = content.encode("utf-8")
+    p.write_bytes(data)
+    return {"path": str(p), "bytes_written": len(data)}
+
+
+def edit_file(
+    path: str | os.PathLike[str],
+    edits: list[tuple[str, str]],
+    *,
+    dry_run: bool = False,
+) -> dict[str, Any]:
+    """Apply a sequence of ``(old_text, new_text)`` substring replacements to a
+    file, in order (first occurrence of each ``old_text``).
+
+    Raises :class:`EditNotAppliedError` if any ``old_text`` is not present at the
+    time it is applied — nothing is written in that case. With ``dry_run`` the new
+    content is computed and diffed but not written. Returns
+    ``{path, edits_applied, dry_run, diff}`` where ``diff`` is a unified diff.
+    """
+    p = _as_path(path)
+    original = p.read_text(encoding="utf-8")
+
+    updated = original
+    for index, (old_text, new_text) in enumerate(edits, start=1):
+        if old_text not in updated:
+            raise EditNotAppliedError(f"edit #{index}: old text not found in {p}: {old_text!r}")
+        updated = updated.replace(old_text, new_text, 1)
+
+    diff = "".join(
+        difflib.unified_diff(
+            original.splitlines(keepends=True),
+            updated.splitlines(keepends=True),
+            fromfile=f"a/{p.name}",
+            tofile=f"b/{p.name}",
+        )
+    )
+
+    if not dry_run:
+        p.write_text(updated, encoding="utf-8")
+
+    return {
+        "path": str(p),
+        "edits_applied": len(edits),
+        "dry_run": dry_run,
+        "diff": diff,
+    }

runspec_fs_core-0.1.0/runspec_fs_core/info.py

@@ -0,0 +1,55 @@
+"""Metadata helpers — the pure logic behind the ``fs`` runnable's
+``get-file-info`` and ``list-allowed-directories`` verbs."""
+
+from __future__ import annotations
+
+import getpass
+import os
+import stat
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+def _iso(ts: float) -> str:
+    return datetime.fromtimestamp(ts, tz=timezone.utc).isoformat()
+
+
+def get_file_info(path: str | os.PathLike[str]) -> dict[str, Any]:
+    """Return detailed metadata for a file or directory: size, timestamps
+    (UTC ISO-8601), octal permissions, and type flags. Returns a plain dict."""
+    p = Path(path).expanduser()
+    st = p.stat()
+    return {
+        "path": str(p),
+        "type": "directory" if p.is_dir() else "file",
+        "size": st.st_size,
+        "created": _iso(st.st_ctime),
+        "modified": _iso(st.st_mtime),
+        "accessed": _iso(st.st_atime),
+        "permissions": oct(stat.S_IMODE(st.st_mode)),
+        "is_directory": p.is_dir(),
+        "is_file": p.is_file(),
+        "is_symlink": p.is_symlink(),
+    }
+
+
+def allowed_directories() -> dict[str, Any]:
+    """Report the effective user and useful starting directories.
+
+    This runnable applies **no software directory jail** — access is bounded by
+    the operating-system permissions of the user the process runs as (the
+    logged-in user, or a ``run_as`` service account). This verb is informational,
+    so an agent knows *who* it is and *where* it starts; it never widens what the
+    OS already allows.
+    """
+    try:
+        user = getpass.getuser()
+    except Exception:  # noqa: BLE001 — getuser can raise if no username resolves
+        user = str(os.getuid()) if hasattr(os, "getuid") else "unknown"
+    return {
+        "user": user,
+        "home": str(Path.home()),
+        "cwd": os.getcwd(),
+        "note": ("No directory jail is enforced. Filesystem access is bounded by the OS permissions of the user this process runs as."),
+    }

runspec_fs_core-0.1.0/runspec_fs_core/search.py

@@ -0,0 +1,50 @@
+"""Search helper — the pure logic behind the ``fs`` runnable's ``search-files``
+verb. Recursively finds files/directories whose name matches a pattern,
+case-insensitively (glob when the pattern contains glob metacharacters, else a
+substring match), honouring a list of exclude globs."""
+
+from __future__ import annotations
+
+import fnmatch
+import os
+from pathlib import Path
+from typing import Any
+
+_GLOB_CHARS = set("*?[]")
+
+
+def _matches(name: str, pattern: str) -> bool:
+    lname = name.lower()
+    lpat = pattern.lower()
+    if _GLOB_CHARS & set(pattern):
+        return fnmatch.fnmatch(lname, lpat)
+    return lpat in lname
+
+
+def search_files(
+    path: str | os.PathLike[str],
+    pattern: str,
+    *,
+    exclude: list[str] | None = None,
+) -> dict[str, Any]:
+    """Recursively search ``path`` for entries whose name matches ``pattern``.
+
+    ``exclude`` is a list of glob patterns; a directory whose name matches an
+    exclude is pruned (not descended into), and matching files are skipped.
+    Returns ``{path, pattern, matches: [str], count}``.
+    """
+    root = Path(path).expanduser()
+    exclude = exclude or []
+    matches: list[str] = []
+
+    for dirpath, dirnames, filenames in os.walk(root):
+        # Prune excluded directories in place so os.walk doesn't descend them.
+        dirnames[:] = [d for d in dirnames if not any(fnmatch.fnmatch(d, pat) for pat in exclude)]
+        for name in list(dirnames) + filenames:
+            if any(fnmatch.fnmatch(name, pat) for pat in exclude):
+                continue
+            if _matches(name, pattern):
+                matches.append(str(Path(dirpath) / name))
+
+    matches.sort()
+    return {"path": str(root), "pattern": pattern, "matches": matches, "count": len(matches)}

runspec_fs_core-0.1.0/tests/test_dirs.py

@@ -0,0 +1,76 @@
+"""Directory helpers against real trees under tmp_path."""
+
+from pathlib import Path
+
+import pytest
+
+from runspec_fs_core.dirs import (
+    create_directory,
+    directory_tree,
+    list_directory,
+    list_directory_with_sizes,
+    move_file,
+)
+
+
+def test_create_directory_idempotent(tmp_path: Path) -> None:
+    target = tmp_path / "a" / "b"
+    assert create_directory(target)["created"] is True
+    assert target.is_dir()
+    assert create_directory(target)["created"] is False
+
+
+def test_list_directory(tmp_path: Path) -> None:
+    (tmp_path / "sub").mkdir()
+    (tmp_path / "file.txt").write_text("x")
+    out = list_directory(tmp_path)
+    names = {(e["name"], e["type"]) for e in out["entries"]}
+    assert ("sub", "directory") in names
+    assert ("file.txt", "file") in names
+    assert out["count"] == 2
+
+
+def test_list_directory_with_sizes_sort_by_size(tmp_path: Path) -> None:
+    (tmp_path / "small.txt").write_text("a")
+    (tmp_path / "big.txt").write_text("a" * 100)
+    out = list_directory_with_sizes(tmp_path, sort_by="size")
+    files = [e for e in out["entries"] if e["type"] == "file"]
+    assert files[0]["name"] == "big.txt"
+    assert out["total_files"] == 2
+    assert out["total_size"] == 101
+
+
+def test_list_directory_with_sizes_bad_sort(tmp_path: Path) -> None:
+    with pytest.raises(ValueError):
+        list_directory_with_sizes(tmp_path, sort_by="nope")
+
+
+def test_directory_tree_with_exclude(tmp_path: Path) -> None:
+    (tmp_path / "keep").mkdir()
+    (tmp_path / "keep" / "f.txt").write_text("x")
+    (tmp_path / "node_modules").mkdir()
+    (tmp_path / "node_modules" / "junk.txt").write_text("y")
+    out = directory_tree(tmp_path, exclude=["node_modules"])
+    child_names = {c["name"] for c in out["tree"]["children"]}
+    assert "keep" in child_names
+    assert "node_modules" not in child_names
+
+
+def test_move_file_renames(tmp_path: Path) -> None:
+    src = tmp_path / "src.txt"
+    src.write_text("data")
+    dst = tmp_path / "dst.txt"
+    out = move_file(src, dst)
+    assert not src.exists()
+    assert dst.read_text() == "data"
+    assert out["destination"] == str(dst)
+
+
+def test_move_file_refuses_existing_destination(tmp_path: Path) -> None:
+    src = tmp_path / "src.txt"
+    src.write_text("a")
+    dst = tmp_path / "dst.txt"
+    dst.write_text("b")
+    with pytest.raises(FileExistsError):
+        move_file(src, dst)
+    assert src.exists()  # nothing moved

runspec_fs_core-0.1.0/tests/test_files.py

@@ -0,0 +1,93 @@
+"""Read / write / edit helpers against real files under tmp_path."""
+
+from pathlib import Path
+
+import pytest
+
+from runspec_fs_core.errors import EditNotAppliedError
+from runspec_fs_core.files import (
+    edit_file,
+    read_media_file,
+    read_multiple_files,
+    read_text_file,
+    write_file,
+)
+
+
+def test_read_text_file_full(tmp_path: Path) -> None:
+    f = tmp_path / "a.txt"
+    f.write_text("one\ntwo\nthree\n")
+    out = read_text_file(f)
+    assert out["content"] == "one\ntwo\nthree\n"
+    assert out["truncated"] is False
+
+
+def test_read_text_file_head_and_tail(tmp_path: Path) -> None:
+    f = tmp_path / "a.txt"
+    f.write_text("l1\nl2\nl3\nl4\n")
+    assert read_text_file(f, head=2)["content"] == "l1\nl2\n"
+    assert read_text_file(f, head=2)["truncated"] is True
+    assert read_text_file(f, tail=1)["content"] == "l4\n"
+
+
+def test_read_text_file_head_tail_mutually_exclusive(tmp_path: Path) -> None:
+    f = tmp_path / "a.txt"
+    f.write_text("x\n")
+    with pytest.raises(ValueError):
+        read_text_file(f, head=1, tail=1)
+
+
+def test_read_text_file_missing_raises_oserror(tmp_path: Path) -> None:
+    with pytest.raises(FileNotFoundError):
+        read_text_file(tmp_path / "nope.txt")
+
+
+def test_read_media_file(tmp_path: Path) -> None:
+    f = tmp_path / "a.bin"
+    f.write_bytes(b"\x00\x01\x02")
+    out = read_media_file(f)
+    assert out["bytes"] == 3
+    assert out["base64"] == "AAEC"
+
+
+def test_read_multiple_files_captures_per_file_errors(tmp_path: Path) -> None:
+    good = tmp_path / "good.txt"
+    good.write_text("hi")
+    out = read_multiple_files([good, tmp_path / "missing.txt"])
+    assert out["count"] == 2
+    assert out["files"][0] == {"path": str(good), "content": "hi"}
+    assert "error" in out["files"][1]
+
+
+def test_write_file(tmp_path: Path) -> None:
+    f = tmp_path / "sub" / "new.txt"
+    f.parent.mkdir()
+    out = write_file(f, "hello")
+    assert f.read_text() == "hello"
+    assert out["bytes_written"] == 5
+
+
+def test_edit_file_applies_ordered_replacements(tmp_path: Path) -> None:
+    f = tmp_path / "a.txt"
+    f.write_text("alpha beta gamma")
+    out = edit_file(f, [("alpha", "ALPHA"), ("gamma", "GAMMA")])
+    assert f.read_text() == "ALPHA beta GAMMA"
+    assert out["edits_applied"] == 2
+    assert out["diff"]
+
+
+def test_edit_file_dry_run_does_not_write(tmp_path: Path) -> None:
+    f = tmp_path / "a.txt"
+    f.write_text("keep me")
+    out = edit_file(f, [("keep", "drop")], dry_run=True)
+    assert f.read_text() == "keep me"
+    assert out["dry_run"] is True
+    assert "drop" in out["diff"]
+
+
+def test_edit_file_missing_old_text_raises_and_does_not_write(tmp_path: Path) -> None:
+    f = tmp_path / "a.txt"
+    f.write_text("original")
+    with pytest.raises(EditNotAppliedError):
+        edit_file(f, [("absent", "x")])
+    assert f.read_text() == "original"

runspec_fs_core-0.1.0/tests/test_search_info.py

@@ -0,0 +1,50 @@
+"""search_files + get_file_info / allowed_directories against tmp_path."""
+
+from pathlib import Path
+
+from runspec_fs_core.info import allowed_directories, get_file_info
+from runspec_fs_core.search import search_files
+
+
+def test_search_files_substring_case_insensitive(tmp_path: Path) -> None:
+    (tmp_path / "Report.txt").write_text("x")
+    (tmp_path / "sub").mkdir()
+    (tmp_path / "sub" / "monthly_report.md").write_text("y")
+    (tmp_path / "other.log").write_text("z")
+    out = search_files(tmp_path, "report")
+    found = {Path(m).name for m in out["matches"]}
+    assert found == {"Report.txt", "monthly_report.md"}
+    assert out["count"] == 2
+
+
+def test_search_files_glob(tmp_path: Path) -> None:
+    (tmp_path / "a.py").write_text("x")
+    (tmp_path / "b.txt").write_text("y")
+    out = search_files(tmp_path, "*.py")
+    assert {Path(m).name for m in out["matches"]} == {"a.py"}
+
+
+def test_search_files_prunes_excluded_dirs(tmp_path: Path) -> None:
+    (tmp_path / "keep").mkdir()
+    (tmp_path / "keep" / "match.txt").write_text("x")
+    (tmp_path / "node_modules").mkdir()
+    (tmp_path / "node_modules" / "match.txt").write_text("y")
+    out = search_files(tmp_path, "match", exclude=["node_modules"])
+    assert all("node_modules" not in m for m in out["matches"])
+    assert out["count"] == 1
+
+
+def test_get_file_info(tmp_path: Path) -> None:
+    f = tmp_path / "a.txt"
+    f.write_text("hello")
+    info = get_file_info(f)
+    assert info["type"] == "file"
+    assert info["size"] == 5
+    assert info["is_file"] is True
+    assert info["permissions"].startswith("0o")
+
+
+def test_allowed_directories_is_informational() -> None:
+    out = allowed_directories()
+    assert "user" in out and "home" in out and "cwd" in out
+    assert "jail" in out["note"].lower()