chore: import upstream snapshot with attribution

python/tests/commands/custom/__init__.py

@@ -0,0 +1,13 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========

python/tests/commands/custom/test_backend_commands.py

@@ -0,0 +1,45 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import pytest
+
+from mirage.resource.ram import RAMResource
+from mirage.types import MountMode
+from mirage.workspace import Workspace
+
+
+def test_memory_backend_provides_commands():
+    backend = RAMResource()
+    cmds = backend.commands()
+    names = {c.name for c in cmds}
+    assert "cat" in names
+    assert "ls" in names
+    assert "grep" in names
+    assert "wc" in names
+    for c in cmds:
+        assert c.resource == "ram"
+
+
+@pytest.mark.asyncio
+async def test_registered_commands_used_for_dispatch():
+    ws = Workspace(
+        {"/tmp/": RAMResource()},
+        mode=MountMode.WRITE,
+    )
+    await ws.ops.write("/tmp/a.txt", b"hello world\n")
+    result = await ws.execute("cat /tmp/a.txt")
+    assert (await result.stdout_str()) == "hello world\n"
+
+    result = await ws.execute("wc -l /tmp/a.txt")
+    assert "1" in (await result.stdout_str())

python/tests/commands/custom/test_dry_run_dispatch.py

@@ -0,0 +1,142 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+
+import pytest
+
+from mirage.commands.registry import RegisteredCommand
+from mirage.commands.spec import SPECS
+from mirage.io.types import IOResult
+from mirage.provision import Precision, ProvisionResult
+from mirage.resource.ram import RAMResource
+from mirage.types import MountMode
+from mirage.workspace import Workspace
+
+
+def _run(coro):
+    return asyncio.run(coro)
+
+
+@pytest.mark.asyncio
+async def test_dry_run_dispatch_with_provision_fn():
+    ws = Workspace(
+        {"/tmp/": RAMResource()},
+        mode=MountMode.WRITE,
+    )
+    await ws.ops.write("/tmp/a.txt", b"hello world")
+
+    async def my_cat(store, paths, *texts, **_extra):
+        return b"hello world", IOResult()
+
+    async def my_cat_dry_run(store, paths, *texts, **_extra):
+        return ProvisionResult(
+            command=f"cat {paths[0]}",
+            network_read_low=11,
+            network_read_high=11,
+            read_ops=1,
+        )
+
+    rc = RegisteredCommand(
+        "cat",
+        spec=SPECS["cat"],
+        resource="ram",
+        filetype=None,
+        fn=my_cat,
+        provision_fn=my_cat_dry_run,
+    )
+    ws._registry.mount_for("/tmp/").register(rc)
+
+    result = await ws.execute("cat /tmp/a.txt", provision=True)
+    assert isinstance(result, ProvisionResult)
+    assert result.network_read_low == 11
+    assert result.read_ops == 1
+
+
+def test_dry_run_dispatch_without_provision_fn():
+    ws = Workspace(
+        {"/tmp/": RAMResource()},
+        mode=MountMode.WRITE,
+    )
+    asyncio.run(ws.ops.write("/tmp/a.txt", b"hello"))
+
+    async def my_cmd(store, paths, *texts, **_extra):
+        return b"ok", IOResult()
+
+    rc = RegisteredCommand(
+        "mycmd",
+        spec=SPECS["cat"],
+        resource="ram",
+        filetype=None,
+        fn=my_cmd,
+    )
+    ws._registry.mount_for("/tmp/").register(rc)
+
+    result = _run(ws.execute("mycmd /tmp/a.txt", provision=True))
+    assert isinstance(result, ProvisionResult)
+    assert result.precision == Precision.UNKNOWN
+
+
+def test_dry_run_command_not_found():
+    ws = Workspace(
+        {"/tmp/": RAMResource()},
+        mode=MountMode.WRITE,
+    )
+    result = _run(ws.execute("nonexistent /tmp/a.txt", provision=True))
+    assert isinstance(result, ProvisionResult)
+    assert result.precision == Precision.UNKNOWN
+
+
+@pytest.mark.asyncio
+async def test_dry_run_filetype_specific():
+    ws = Workspace(
+        {"/tmp/": RAMResource()},
+        mode=MountMode.WRITE,
+    )
+    await ws.ops.write("/tmp/data.avro", b"avro-bytes")
+
+    async def cat_generic(store, paths, *texts, **_extra):
+        return b"generic", IOResult()
+
+    async def cat_generic_dry(store, paths, *texts, **_extra):
+        return ProvisionResult(command="cat generic",
+                               network_read_low=999,
+                               network_read_high=999)
+
+    async def cat_avro(store, paths, *texts, **_extra):
+        return b"avro", IOResult()
+
+    async def cat_avro_dry(store, paths, *texts, **_extra):
+        return ProvisionResult(command="cat avro",
+                               network_read_low=10,
+                               network_read_high=10)
+
+    mount = ws._registry.mount_for("/tmp/")
+    mount.register(
+        RegisteredCommand("cat",
+                          spec=SPECS["cat"],
+                          resource="ram",
+                          filetype=None,
+                          fn=cat_generic,
+                          provision_fn=cat_generic_dry))
+    mount.register(
+        RegisteredCommand("cat",
+                          spec=SPECS["cat"],
+                          resource="ram",
+                          filetype=".avro",
+                          fn=cat_avro,
+                          provision_fn=cat_avro_dry))
+
+    result = await ws.execute("cat /tmp/data.avro", provision=True)
+    assert result.network_read_low == 10

python/tests/commands/custom/test_dry_run_registration.py

@@ -0,0 +1,76 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+from mirage.commands.registry import RegisteredCommand, command
+from mirage.commands.spec import CommandSpec
+from mirage.io.types import IOResult
+from mirage.provision import ProvisionResult
+
+
+async def my_cmd(backend, paths, *texts, **_extra):
+    return b"ok", IOResult()
+
+
+async def my_cmd_dry_run(backend, paths, *texts, **_extra):
+    return ProvisionResult(command="my_cmd",
+                           network_read_low=100,
+                           network_read_high=100)
+
+
+def test_registered_command_has_provision_fn():
+    rc = RegisteredCommand(
+        name="mycmd",
+        spec=CommandSpec(),
+        resource="ram",
+        filetype=None,
+        fn=my_cmd,
+        provision_fn=my_cmd_dry_run,
+    )
+    assert rc.provision_fn is my_cmd_dry_run
+
+
+def test_registered_command_provision_fn_defaults_none():
+    rc = RegisteredCommand(
+        name="mycmd",
+        spec=CommandSpec(),
+        resource="ram",
+        filetype=None,
+        fn=my_cmd,
+    )
+    assert rc.provision_fn is None
+
+
+def test_command_decorator_with_dry_run():
+
+    @command("mycmd",
+             resource="ram",
+             spec=CommandSpec(),
+             provision=my_cmd_dry_run)
+    async def mycmd(backend, paths, *texts, **_extra):
+        return b"ok", IOResult()
+
+    rcs = mycmd._registered_commands
+    assert len(rcs) == 1
+    assert rcs[0].provision_fn is my_cmd_dry_run
+
+
+def test_command_decorator_without_dry_run():
+
+    @command("mycmd2", resource="ram", spec=CommandSpec())
+    async def mycmd2(backend, paths, *texts, **_extra):
+        return b"ok", IOResult()
+
+    rcs = mycmd2._registered_commands
+    assert len(rcs) == 1
+    assert rcs[0].provision_fn is None

python/tests/commands/custom/test_filetype_fns.py

@@ -0,0 +1,128 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+
+from mirage.commands.registry import RegisteredCommand
+from mirage.commands.spec import SPECS
+from mirage.io.types import IOResult
+from mirage.resource.ram import RAMResource
+from mirage.types import MountMode
+from mirage.workspace import Workspace
+
+
+def _run(ws, cmd, cwd="/"):
+    ws._cwd = cwd
+    return asyncio.run(ws.execute(cmd))
+
+
+def test_filetype_fns_passed_to_generic_command():
+    ws = Workspace(
+        {"/tmp/": RAMResource()},
+        mode=MountMode.WRITE,
+    )
+    asyncio.run(ws.ops.write("/tmp/a.txt", b"hello"))
+
+    received = {}
+
+    async def my_cat(store, paths, *texts, filetype_fns=None, **kwargs):
+        received["filetype_fns"] = filetype_fns
+        return b"ok", IOResult()
+
+    async def my_cat_parquet(store, paths, *texts, **kwargs):
+        return b"parquet-ok", IOResult()
+
+    mount = ws._registry.mount_for("/tmp/")
+    mount.register(
+        RegisteredCommand("mycat",
+                          spec=SPECS["cat"],
+                          resource="ram",
+                          filetype=None,
+                          fn=my_cat))
+    mount.register(
+        RegisteredCommand("mycat",
+                          spec=SPECS["cat"],
+                          resource="ram",
+                          filetype=".parquet",
+                          fn=my_cat_parquet))
+
+    _run(ws, "mycat /tmp/a.txt")
+    assert received["filetype_fns"] is not None
+    assert ".parquet" in received["filetype_fns"]
+    assert received["filetype_fns"][".parquet"] is my_cat_parquet
+
+
+def test_filetype_fns_not_passed_to_filetype_command():
+    ws = Workspace(
+        {"/tmp/": RAMResource()},
+        mode=MountMode.WRITE,
+    )
+    asyncio.run(ws.ops.write("/tmp/a.parquet", b"fake-parquet"))
+
+    received = {}
+
+    async def my_cat(store, paths, *texts, filetype_fns=None, **kwargs):
+        return b"generic", IOResult()
+
+    async def my_cat_parquet(store,
+                             paths,
+                             *texts,
+                             filetype_fns=None,
+                             **kwargs):
+        received["filetype_fns"] = filetype_fns
+        return b"parquet", IOResult()
+
+    mount = ws._registry.mount_for("/tmp/")
+    mount.register(
+        RegisteredCommand("mycat",
+                          spec=SPECS["cat"],
+                          resource="ram",
+                          filetype=None,
+                          fn=my_cat))
+    mount.register(
+        RegisteredCommand("mycat",
+                          spec=SPECS["cat"],
+                          resource="ram",
+                          filetype=".parquet",
+                          fn=my_cat_parquet))
+
+    _run(ws, "mycat /tmp/a.parquet")
+    fns = received.get("filetype_fns", {})
+    assert fns is None or len(fns) == 0
+
+
+def test_filetype_fns_empty_when_no_variants():
+    ws = Workspace(
+        {"/tmp/": RAMResource()},
+        mode=MountMode.WRITE,
+    )
+    asyncio.run(ws.ops.write("/tmp/a.txt", b"hello"))
+
+    received = {}
+
+    async def my_echo(store, paths, *texts, filetype_fns=None, **kwargs):
+        received["filetype_fns"] = filetype_fns
+        return b"ok", IOResult()
+
+    ws._registry.mount_for("/tmp/").register(
+        RegisteredCommand("myecho",
+                          spec=SPECS["echo"],
+                          resource="ram",
+                          filetype=None,
+                          fn=my_echo))
+
+    _run(ws, "myecho /tmp/a.txt")
+    fns = received.get("filetype_fns", {})
+    assert fns is not None
+    assert len(fns) == 0

python/tests/commands/custom/test_general_commands.py

@@ -0,0 +1,28 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+from mirage.resource.ram import RAMResource
+
+
+def test_memory_backend_commands_exist():
+    cmds = RAMResource().commands()
+    names = {c.name for c in cmds}
+    assert "cat" in names
+    assert "ls" in names
+
+
+def test_memory_backend_commands_have_memory_backend():
+    cmds = RAMResource().commands()
+    for cmd in cmds:
+        assert cmd.resource == "ram"

python/tests/commands/custom/test_registered_command.py

@@ -0,0 +1,87 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import pytest
+
+from mirage.commands.registry import RegisteredCommand, command
+from mirage.commands.spec import SPECS, CommandSpec, Operand, OperandKind
+from mirage.io.types import IOResult
+
+
+def test_registered_command_dataclass():
+
+    async def dummy(backend, paths, *texts, stdin=None, **flags):
+        return b"ok", IOResult()
+
+    rc = RegisteredCommand(
+        name="cat",
+        spec=SPECS["cat"],
+        resource="s3",
+        filetype=None,
+        fn=dummy,
+    )
+    assert rc.name == "cat"
+    assert rc.resource == "s3"
+    assert rc.filetype is None
+    assert rc.fn is dummy
+
+
+def test_command_decorator_attaches_metadata():
+
+    @command("myls",
+             resource="s3",
+             spec=CommandSpec(rest=Operand(kind=OperandKind.PATH)))
+    async def my_ls(backend, paths, *texts, stdin=None, **flags):
+        return b"ok", IOResult()
+
+    assert hasattr(my_ls, "_registered_commands")
+    assert len(my_ls._registered_commands) == 1
+    rc = my_ls._registered_commands[0]
+    assert rc.name == "myls"
+    assert rc.resource == "s3"
+    assert rc.filetype is None
+
+
+def test_command_decorator_stacking():
+
+    @command("cat", resource="s3", spec=SPECS["cat"])
+    @command("cat", resource="ram", spec=SPECS["cat"])
+    async def cat_impl(backend, paths, *texts, stdin=None, **flags):
+        return b"ok", IOResult()
+
+    assert len(cat_impl._registered_commands) == 2
+    backends = {rc.resource for rc in cat_impl._registered_commands}
+    assert backends == {"s3", "ram"}
+
+
+def test_command_decorator_with_filetype():
+
+    @command("cat",
+             resource="s3",
+             filetype=".avro",
+             spec=CommandSpec(rest=Operand(kind=OperandKind.PATH)))
+    async def cat_avro(backend, paths, *texts, stdin=None, **flags):
+        return b"ok", IOResult()
+
+    rc = cat_avro._registered_commands[0]
+    assert rc.filetype == ".avro"
+    assert rc.resource == "s3"
+
+
+def test_command_decorator_requires_spec():
+    with pytest.raises(TypeError):
+
+        @command("myls", resource="s3")
+        async def my_ls(backend, paths, *texts, stdin=None, **flags):
+            return b"ok", IOResult()

python/tests/commands/custom/test_registered_dispatch.py

@@ -0,0 +1,141 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+
+import pytest
+
+from mirage.commands.registry import RegisteredCommand
+from mirage.commands.spec import SPECS, CommandSpec
+from mirage.io.types import IOResult
+from mirage.resource.ram import RAMResource
+from mirage.types import MountMode
+from mirage.workspace import Workspace
+
+
+@pytest.mark.asyncio
+async def test_registered_command_dispatch():
+    ws = Workspace(
+        {"/tmp/": RAMResource()},
+        mode=MountMode.WRITE,
+    )
+    await ws.ops.write("/tmp/a.txt", b"hello")
+
+    async def my_cat(store, paths, *texts, stdin=None, **flags):
+        return b"custom-cat", IOResult()
+
+    rc = RegisteredCommand("cat",
+                           spec=SPECS["cat"],
+                           resource="ram",
+                           filetype=None,
+                           fn=my_cat)
+    ws._registry.mount_for("/tmp/").register(rc)
+
+    ws._cwd = "/"
+    result = await ws.execute("cat /tmp/a.txt")
+    assert result.stdout == b"custom-cat"
+
+
+@pytest.mark.asyncio
+async def test_registered_filetype_dispatch():
+    ws = Workspace(
+        {"/tmp/": RAMResource()},
+        mode=MountMode.WRITE,
+    )
+    await ws.ops.write("/tmp/data.avro", b"avro-data")
+
+    async def cat_avro(store, paths, *texts, stdin=None, **flags):
+        return b"avro-output", IOResult()
+
+    rc = RegisteredCommand("cat",
+                           spec=SPECS["cat"],
+                           resource="ram",
+                           filetype=".avro",
+                           fn=cat_avro)
+    ws._registry.mount_for("/tmp/").register(rc)
+
+    ws._cwd = "/"
+    result = await ws.execute("cat /tmp/data.avro")
+    assert result.stdout == b"avro-output"
+
+
+@pytest.mark.asyncio
+async def test_filetype_takes_priority_over_generic():
+    ws = Workspace(
+        {"/tmp/": RAMResource()},
+        mode=MountMode.WRITE,
+    )
+    await ws.ops.write("/tmp/data.avro", b"avro-data")
+
+    async def cat_generic(store, paths, *texts, stdin=None, **flags):
+        return b"generic", IOResult()
+
+    async def cat_avro(store, paths, *texts, stdin=None, **flags):
+        return b"avro", IOResult()
+
+    mount = ws._registry.mount_for("/tmp/")
+    mount.register(
+        RegisteredCommand("cat",
+                          spec=SPECS["cat"],
+                          resource="ram",
+                          filetype=None,
+                          fn=cat_generic))
+    mount.register(
+        RegisteredCommand("cat",
+                          spec=SPECS["cat"],
+                          resource="ram",
+                          filetype=".avro",
+                          fn=cat_avro))
+
+    ws._cwd = "/"
+    result = await ws.execute("cat /tmp/data.avro")
+    assert result.stdout == b"avro"
+
+    await ws.ops.write("/tmp/data.csv", b"csv-data")
+    result = await ws.execute("cat /tmp/data.csv")
+    assert result.stdout == b"generic"
+
+
+@pytest.mark.asyncio
+async def test_registered_falls_back_to_builtin():
+    ws = Workspace(
+        {"/tmp/": RAMResource()},
+        mode=MountMode.WRITE,
+    )
+    await ws.ops.write("/tmp/a.txt", b"hello world")
+    ws._cwd = "/"
+    result = await ws.execute("wc -l /tmp/a.txt")
+    out = await result.stdout_str()
+    assert "0" in out or "1" in out
+
+
+def test_general_command_dispatch():
+    ws = Workspace(
+        {"/tmp/": RAMResource()},
+        mode=MountMode.WRITE,
+    )
+
+    async def my_stat(store, paths, *texts, stdin=None, **flags):
+        return b"custom-stat", IOResult()
+
+    rc = RegisteredCommand("stat",
+                           spec=CommandSpec(),
+                           resource="ram",
+                           filetype=None,
+                           fn=my_stat)
+    ws._registry.mount_for("/tmp/").register(rc)
+
+    ws._cwd = "/tmp"
+    result = asyncio.run(ws.execute("stat /tmp/file.txt"))
+    assert result.stdout == b"custom-stat"

python/tests/commands/custom/test_workspace_register.py

@@ -0,0 +1,97 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+
+from mirage.commands.registry import command
+from mirage.commands.spec import CommandSpec, Operand, OperandKind
+from mirage.io.types import IOResult
+from mirage.resource.ram import RAMResource
+from mirage.types import MountMode
+from mirage.workspace import Workspace
+
+
+def _register(ws, fn):
+    mount = ws._registry.mount_for("/tmp/")
+    for rc in fn._registered_commands:
+        mount.register(rc)
+
+
+def test_workspace_accepts_commands_param():
+
+    @command("myecho",
+             resource="ram",
+             spec=CommandSpec(rest=Operand(kind=OperandKind.TEXT)))
+    async def my_echo(store, paths, *texts, cwd="/", stdin=None, **flags):
+        return " ".join(texts).encode(), IOResult()
+
+    ws = Workspace(
+        {"/tmp/": RAMResource()},
+        mode=MountMode.WRITE,
+    )
+    _register(ws, my_echo)
+
+    async def _run():
+        result = await ws.execute("myecho hello world")
+        return (await result.stdout_str()).strip()
+
+    assert asyncio.run(_run()) == "hello world"
+
+
+def test_workspace_register_method():
+    ws = Workspace(
+        {"/tmp/": RAMResource()},
+        mode=MountMode.WRITE,
+    )
+
+    @command("myecho",
+             resource="ram",
+             spec=CommandSpec(rest=Operand(kind=OperandKind.TEXT)))
+    async def my_echo(store, paths, *texts, cwd="/", stdin=None, **flags):
+        return " ".join(texts).encode(), IOResult()
+
+    _register(ws, my_echo)
+
+    async def _run():
+        result = await ws.execute("myecho hello")
+        return (await result.stdout_str()).strip()
+
+    assert asyncio.run(_run()) == "hello"
+
+
+def test_workspace_user_command_overrides_builtin():
+
+    @command("stat", resource="ram", spec=CommandSpec())
+    async def my_stat(store, paths, *texts, stdin=None, **flags):
+        return b"custom-stat", IOResult()
+
+    ws = Workspace(
+        {"/tmp/": RAMResource()},
+        mode=MountMode.WRITE,
+    )
+    _register(ws, my_stat)
+    ws._cwd = "/tmp/"
+
+    async def _run():
+        result = await ws.execute("stat /tmp/file.txt")
+        return (await result.stdout_str()).strip()
+
+    assert asyncio.run(_run()) == "custom-stat"
+
+
+def test_backend_commands_method_returns_commands():
+    backend = RAMResource()
+    cmds = backend.commands()
+    assert len(cmds) > 0
+    assert all(c.resource == "ram" for c in cmds)