runspec-fs 0.1.0__tar.gz

runspec_fs-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-0.1.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# runspec-fs Changelog
+
+## [0.1.0] — 2026-07-25
+
+Initial release.
+
+A single runnable, `fs`, with a verb per tool of the
+[Filesystem MCP server](https://github.com/modelcontextprotocol/servers/tree/HEAD/src/filesystem)
+— read / write / edit / list / tree / search / move / stat. `runspec serve`
+re-expands each verb into its own leaf MCP tool (`fs_read-text-file`,
+`fs_write-file`, …), so a runspec-console agent can call them individually over
+SSH on any fleet host — giving it local **and** remote filesystem access with
+per-verb confirm gates and no extra process on the host.
+
+- **Reads (autonomous)** — `read-text-file` (`--head` / `--tail`),
+  `read-media-file` (base64 + MIME), `read-multiple-files`, `list-directory`,
+  `list-directory-with-sizes` (`--sort-by name|size`), `directory-tree`
+  (`--exclude`), `search-files` (glob or substring, `--exclude`), `get-file-info`,
+  `list-allowed-directories`.
+- **Mutations (confirm)** — `write-file`, `edit-file`, `create-directory`,
+  `move-file`.
+
+`edit-file` takes its edits as two parallel repeatable args — `--old-text` and
+`--new-text`, paired by position — rather than a JSON blob, so agents pass two
+typed string arrays (no new runspec arg type was needed).
+
+**No directory jail** — filesystem access is bounded by the OS permissions of the
+user the process runs as (the logged-in user, or a `run_as` service account).
+The pure logic lives in `runspec-fs-core` (no runspec dependency), re-exported
+here for corporate-wrapping.

runspec_fs-0.1.0/PKG-INFO

@@ -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/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "runspec-fs"
+version = "0.1.0"
+requires-python = ">=3.10"
+description = "Filesystem runnable for runspec — read and manipulate local/remote filesystems, ported from the Filesystem MCP server"
+dependencies = [
+    # 0.44.0 surfaces inherited args on each leaf subcommand's MCP tool via
+    # `runspec serve`; fs has no globals, but the floor keeps serve behaviour
+    # consistent with the other subcommand runnables.
+    "runspec>=0.44.0",
+    "runspec-fs-core>=0.1.0",
+]
+
+[project.scripts]
+# Entry point name MUST match the runnable name in runspec.toml (`fs`).
+fs = "runspec_fs.cli:main"
+
+[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-0.1.0/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-0.1.0/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-0.1.0/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/tests/test_cli.py

@@ -0,0 +1,52 @@
+"""Wrapper-only logic (the edit-pairing) plus an end-to-end run of a couple of
+verbs through the installed `fs` entry point against tmp_path."""
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+from runspec_fs.cli import _pair_edits
+
+
+def test_pair_edits_ok() -> None:
+    assert _pair_edits(["a", "b"], ["x", "y"]) == [("a", "x"), ("b", "y")]
+
+
+def test_pair_edits_mismatch_raises() -> None:
+    with pytest.raises(ValueError, match="count mismatch"):
+        _pair_edits(["a"], ["x", "y"])
+
+
+def _run_fs(argv: list[str], tmp_path: Path) -> dict:
+    """Invoke the runnable in-process via `python -m runspec_fs.cli`, pointing
+    runspec at the packaged spec. Returns the parsed JSON stdout."""
+    spec = Path(__file__).parent.parent / "runspec_fs" / "runspec.toml"
+    env = {**os.environ, "RUNSPEC_CONFIG": str(spec)}
+    proc = subprocess.run(
+        [sys.executable, "-c", "from runspec_fs.cli import main; main()", *argv],
+        capture_output=True,
+        text=True,
+        env=env,
+        cwd=tmp_path,
+    )
+    assert proc.returncode == 0, proc.stderr
+    return json.loads(proc.stdout.strip().splitlines()[-1])
+
+
+def test_list_directory_end_to_end(tmp_path: Path) -> None:
+    (tmp_path / "hello.txt").write_text("hi")
+    out = _run_fs(["list-directory", "--path", str(tmp_path)], tmp_path)
+    names = {e["name"] for e in out["entries"]}
+    assert "hello.txt" in names
+
+
+def test_read_text_file_head_end_to_end(tmp_path: Path) -> None:
+    f = tmp_path / "a.txt"
+    f.write_text("l1\nl2\nl3\n")
+    out = _run_fs(["read-text-file", "--path", str(f), "--head", "2"], tmp_path)
+    assert out["content"] == "l1\nl2\n"
+    assert out["truncated"] is True

runspec_fs-0.1.0/tests/test_spec.py

@@ -0,0 +1,74 @@
+"""Wiring / parsing tests for the `fs` runnable — no mocks, real spec."""
+
+from pathlib import Path
+
+from runspec.testing import ParseHarness
+
+SPEC = Path(__file__).parent.parent / "runspec_fs" / "runspec.toml"
+
+
+def _harness() -> ParseHarness:
+    return ParseHarness(script_name="fs", config_path=SPEC)
+
+
+def test_smoke_all_verbs() -> None:
+    h = _harness()
+    # Walk the whole verb tree: --help exits 0, require-command is enforced,
+    # omitting required args exits 1, and a fully-populated invocation parses.
+    h.smoke(
+        values={
+            "path": ".",
+            "pattern": "x",
+            "content": "hi",
+            "paths": ["."],
+            "old-text": ["a"],
+            "new-text": ["b"],
+        }
+    )
+    h.close()
+
+
+def test_read_text_file_coerces() -> None:
+    h = _harness()
+    spec = h.expect_ok(["read-text-file", "--path", "README.md", "--head", "5"])
+    assert spec.runspec_command == "read-text-file"
+    assert spec.head.value == 5
+    assert spec.tail.value is None
+    h.close()
+
+
+def test_bad_choice_rejected() -> None:
+    h = _harness()
+    h.expect_exit(
+        ["list-directory-with-sizes", "--path", ".", "--sort-by", "nope"],
+        contains="sort-by",
+    )
+    h.close()
+
+
+def test_missing_required_path_rejected() -> None:
+    h = _harness()
+    h.expect_exit(["list-directory"], contains="path")
+    h.close()
+
+
+def test_edit_file_repeated_args_build_lists() -> None:
+    h = _harness()
+    spec = h.expect_ok(
+        [
+            "edit-file",
+            "--path",
+            "a.txt",
+            "--old-text",
+            "foo",
+            "--old-text",
+            "baz",
+            "--new-text",
+            "bar",
+            "--new-text",
+            "qux",
+        ]
+    )
+    assert spec.old_text.value == ["foo", "baz"]
+    assert spec.new_text.value == ["bar", "qux"]
+    h.close()