runspec-fs 0.1.0__py3-none-any.whl

runspec_fs/__init__.py

@@ -0,0 +1,48 @@
+"""runspec-fs — filesystem operations as a runspec runnable (the ``fs`` runnable).
+
+Ported from the
+`Filesystem MCP server <https://github.com/modelcontextprotocol/servers/tree/HEAD/src/filesystem>`_.
+The pure logic lives in ``runspec-fs-core`` (importable with **no** runspec
+dependency); this package wraps each helper as a verb of the ``fs`` runnable and
+is what ``runspec local`` / ``runspec serve`` discover.
+
+The core helpers are re-exported here for convenience / back-compat, so a caller
+that already depends on ``runspec-fs`` can ``from runspec_fs import
+read_text_file`` without also naming ``runspec-fs-core``:
+"""
+
+from runspec_fs_core import (
+    EditNotAppliedError,
+    FsCoreError,
+    allowed_directories,
+    create_directory,
+    directory_tree,
+    edit_file,
+    get_file_info,
+    list_directory,
+    list_directory_with_sizes,
+    move_file,
+    read_media_file,
+    read_multiple_files,
+    read_text_file,
+    search_files,
+    write_file,
+)
+
+__all__ = [
+    "FsCoreError",
+    "EditNotAppliedError",
+    "read_text_file",
+    "read_media_file",
+    "read_multiple_files",
+    "write_file",
+    "edit_file",
+    "create_directory",
+    "list_directory",
+    "list_directory_with_sizes",
+    "directory_tree",
+    "move_file",
+    "search_files",
+    "get_file_info",
+    "allowed_directories",
+]

runspec_fs/cli.py

@@ -0,0 +1,95 @@
+"""cli.py — the ``fs`` entry point.
+
+One binary, a verb per Filesystem MCP tool. ``rs.parse("fs")`` resolves the
+subcommand and its args; we dispatch on ``spec.runspec_command``, unpack each
+``.value`` at the boundary, and delegate the actual work to
+:mod:`runspec_fs_core`. Failures (the ``runspec_fs_core`` errors, the stdlib
+``OSError`` family, and arg-shape ``ValueError``s such as an ``--old-text`` /
+``--new-text`` count mismatch) become a JSON ``{"error": ...}`` payload + a
+non-zero exit — the shape the CLI/agent surface expects.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+import runspec as rs
+from runspec_fs_core import (
+    allowed_directories,
+    create_directory,
+    directory_tree,
+    edit_file,
+    get_file_info,
+    list_directory,
+    list_directory_with_sizes,
+    move_file,
+    read_media_file,
+    read_multiple_files,
+    read_text_file,
+    search_files,
+    write_file,
+)
+from runspec_fs_core.errors import FsCoreError
+
+
+def _emit(payload: dict[str, Any]) -> None:
+    print(json.dumps(payload, default=str))
+
+
+def _pair_edits(old_text: list[str], new_text: list[str]) -> list[tuple[str, str]]:
+    """Zip the two parallel ``--old-text`` / ``--new-text`` lists into
+    ``(old, new)`` pairs, erroring if their counts differ."""
+    if len(old_text) != len(new_text):
+        raise ValueError(f"--old-text / --new-text count mismatch: {len(old_text)} vs {len(new_text)} (pair them by position)")
+    return list(zip(old_text, new_text, strict=False))
+
+
+def _dispatch(spec: rs.RunSpec) -> dict[str, Any]:
+    command = spec.runspec_command
+
+    if command == "read-text-file":
+        return read_text_file(spec.path.value, head=spec.head.value, tail=spec.tail.value)
+    if command == "read-media-file":
+        return read_media_file(spec.path.value)
+    if command == "read-multiple-files":
+        return read_multiple_files(spec.paths.value)
+    if command == "list-directory":
+        return list_directory(spec.path.value)
+    if command == "list-directory-with-sizes":
+        return list_directory_with_sizes(spec.path.value, sort_by=spec.sort_by.value)
+    if command == "directory-tree":
+        return directory_tree(spec.path.value, exclude=spec.exclude.value or None)
+    if command == "search-files":
+        return search_files(spec.path.value, spec.pattern.value, exclude=spec.exclude.value or None)
+    if command == "get-file-info":
+        return get_file_info(spec.path.value)
+    if command == "list-allowed-directories":
+        return allowed_directories()
+    if command == "write-file":
+        return write_file(spec.path.value, spec.content.value)
+    if command == "edit-file":
+        edits = _pair_edits(spec.old_text.value, spec.new_text.value)
+        return edit_file(spec.path.value, edits, dry_run=spec.dry_run.value)
+    if command == "create-directory":
+        return create_directory(spec.path.value)
+    if command == "move-file":
+        return move_file(spec.source.value, spec.destination.value)
+
+    # require-command = true makes a bare invocation unreachable.
+    raise SystemExit("no command — see `fs --help`")  # pragma: no cover
+
+
+def main() -> None:
+    spec = rs.parse("fs")
+    try:
+        result = _dispatch(spec)
+    except (FsCoreError, OSError, ValueError) as exc:
+        _emit({"error": str(exc), "kind": type(exc).__name__})
+        sys.exit(1)
+    _emit(result)
+
+
+if __name__ == "__main__":
+    main()

runspec_fs/runspec.toml

@@ -0,0 +1,123 @@
+#:schema https://runspec.app/runspec.schema.json
+
+# runspec-fs — filesystem operations as a runspec runnable, ported from the
+# Filesystem MCP server:
+#   https://github.com/modelcontextprotocol/servers/tree/HEAD/src/filesystem
+#
+# One runnable, `fs`, with a verb per MCP tool. `runspec serve` re-expands each
+# verb into its own leaf MCP tool (fs_read-text-file, fs_write-file, …), so a
+# runspec-console agent calls them individually — over SSH on any fleet host,
+# giving local AND remote filesystem access with per-verb confirm gates.
+#
+# No directory jail is enforced: access is bounded by the OS permissions of the
+# user the process runs as (the logged-in user, or a `run_as` service account).
+# A wrong path the agent picks and a human confirms still can't exceed what that
+# user could already do on the host.
+
+[config]
+autonomy-default = "confirm"
+
+[config.logging]
+store = "per-run"
+
+[fs]
+description = "Read and manipulate the filesystem on this host (local, or remote via runspec-console)"
+output = "json"
+require-command = true
+examples = [
+  {cmd = "fs list-directory --path .", description = "List the current directory"},
+  {cmd = "fs read-text-file --path README.md --head 20", description = "Read the first 20 lines of a file"},
+  {cmd = "fs search-files --path . --pattern '*.py'", description = "Find Python files recursively"},
+  {cmd = "fs edit-file --path a.txt --old-text foo --new-text bar", description = "Replace 'foo' with 'bar'"},
+]
+
+# ── reads / metadata → autonomous ──────────────────────────────────────────
+
+[fs.commands.read-text-file]
+description = "Read a file as UTF-8 text; optionally only the first N (--head) or last N (--tail) lines"
+autonomy = "autonomous"
+[fs.commands.read-text-file.args]
+path = {type = "path", required = true, description = "File to read"}
+head = {type = "int", required = false, description = "Return only the first N lines"}
+tail = {type = "int", required = false, description = "Return only the last N lines"}
+
+[fs.commands.read-media-file]
+description = "Read a binary/media file and return it base64-encoded with its MIME type"
+autonomy = "autonomous"
+[fs.commands.read-media-file.args]
+path = {type = "path", required = true, description = "File to read"}
+
+[fs.commands.read-multiple-files]
+description = "Read several files at once; a failed read is reported per-file without aborting the batch"
+autonomy = "autonomous"
+[fs.commands.read-multiple-files.args]
+paths = {type = "path", multiple = true, required = true, description = "Files to read (repeat --paths per file)"}
+
+[fs.commands.list-directory]
+description = "List a directory's immediate contents, each tagged file or directory"
+autonomy = "autonomous"
+[fs.commands.list-directory.args]
+path = {type = "path", required = true, description = "Directory to list"}
+
+[fs.commands.list-directory-with-sizes]
+description = "List a directory's contents with per-entry sizes and totals"
+autonomy = "autonomous"
+[fs.commands.list-directory-with-sizes.args]
+path = {type = "path", required = true, description = "Directory to list"}
+sort-by = {type = "choice", options = ["name", "size"], default = "name", description = "Sort order (size is descending)"}
+
+[fs.commands.directory-tree]
+description = "Return a recursive JSON tree of a directory"
+autonomy = "autonomous"
+[fs.commands.directory-tree.args]
+path = {type = "path", required = true, description = "Directory to walk"}
+exclude = {type = "str", multiple = true, required = false, description = "Glob patterns to prune (repeat --exclude)"}
+
+[fs.commands.search-files]
+description = "Recursively find files/directories whose name matches a pattern (glob, or case-insensitive substring)"
+autonomy = "autonomous"
+[fs.commands.search-files.args]
+path = {type = "path", required = true, description = "Directory to search under"}
+pattern = {type = "str", required = true, description = "Glob (e.g. '*.py') or a case-insensitive substring"}
+exclude = {type = "str", multiple = true, required = false, description = "Glob patterns to prune (repeat --exclude)"}
+
+[fs.commands.get-file-info]
+description = "Return detailed metadata for a file or directory (size, timestamps, permissions)"
+autonomy = "autonomous"
+[fs.commands.get-file-info.args]
+path = {type = "path", required = true, description = "File or directory to stat"}
+
+[fs.commands.list-allowed-directories]
+description = "Report the effective user and starting directories (informational — no directory jail is enforced)"
+autonomy = "autonomous"
+
+# ── mutations → confirm ────────────────────────────────────────────────────
+
+[fs.commands.write-file]
+description = "Create a new file or overwrite an existing one with UTF-8 text"
+autonomy = "confirm"
+[fs.commands.write-file.args]
+path = {type = "path", required = true, description = "File to write"}
+content = {type = "str", required = true, description = "File contents"}
+
+[fs.commands.edit-file]
+description = "Apply ordered old→new substring replacements to a file; returns a unified diff. Pair each --old-text with a --new-text by position."
+autonomy = "confirm"
+[fs.commands.edit-file.args]
+path = {type = "path", required = true, description = "File to edit"}
+old-text = {type = "str", multiple = true, required = true, description = "Text to find (repeat --old-text; paired by position with --new-text)"}
+new-text = {type = "str", multiple = true, required = true, description = "Replacement text (repeat --new-text; paired by position with --old-text)"}
+dry-run = {type = "flag", default = false, description = "Compute and diff the edits without writing"}
+
+[fs.commands.create-directory]
+description = "Create a directory (and any missing parents); idempotent"
+autonomy = "confirm"
+[fs.commands.create-directory.args]
+path = {type = "path", required = true, description = "Directory to create"}
+
+[fs.commands.move-file]
+description = "Move or rename a file/directory; fails if the destination already exists"
+autonomy = "confirm"
+[fs.commands.move-file.args]
+source = {type = "path", required = true, description = "Path to move"}
+destination = {type = "path", required = true, description = "New path (must not already exist)"}

runspec_fs-0.1.0.dist-info/METADATA

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: runspec-fs
+Version: 0.1.0
+Summary: Filesystem runnable for runspec — read and manipulate local/remote filesystems, ported from the Filesystem MCP server
+Requires-Python: >=3.10
+Requires-Dist: runspec-fs-core>=0.1.0
+Requires-Dist: runspec>=0.44.0
+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-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+runspec_fs/__init__.py,sha256=mWLM-DPhfuSM5xyO6ohSM3giS_jQG-a1qWfte9llY4Q,1324
+runspec_fs/cli.py,sha256=x3haDpoG7M8TkVAhQ80VOTcEhxjtNAQ37tVZo8fsg-g,3444
+runspec_fs/runspec.toml,sha256=UcooLiyF8Eollgo86LjHarlmh3OT9prRnlPtzsSKYQY,6333
+runspec_fs-0.1.0.dist-info/METADATA,sha256=9np0tqUY5-7m_LoA7UAkMSD649UGbI22rkMTXrgk7H0,420
+runspec_fs-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+runspec_fs-0.1.0.dist-info/entry_points.txt,sha256=7cGeDLaU8E86XOc1dKjoOQylUgbILv7XUHlKJAtZd4w,43
+runspec_fs-0.1.0.dist-info/RECORD,,

runspec_fs-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

runspec_fs-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+fs = runspec_fs.cli:main