Skip to content

refactor(bindings): unify mount API, read-only by default#1154

Merged
chaliy merged 5 commits intomainfrom
claude/mounts-readonly-default-58xnr
Apr 8, 2026
Merged

refactor(bindings): unify mount API, read-only by default#1154
chaliy merged 5 commits intomainfrom
claude/mounts-readonly-default-58xnr

Conversation

@chaliy
Copy link
Copy Markdown
Contributor

@chaliy chaliy commented Apr 8, 2026

Summary

  • Safe default: mounts are read-only by default — callers must explicitly pass writable: true to enable host writes
  • Unified API: JS and Python bindings now expose the same conceptual mount surface (files dict + mounts list + runtime mount()/unmount())
  • Spec parity: added binding parity requirement to specs/003-vfs.md and maintenance checklist to specs/012-maintenance.md

Before → After

JS:

// Before: readOnly flag (unsafe if omitted)
mounts: [{ path: "/docs", root: "/real/path", readOnly: true }]
bash.mountReal(host, vfs, readOnly)

// After: writable flag (safe if omitted)
mounts: [{ path: "/docs", root: "/real/path" }]  // read-only
bash.mount(host, vfs)                              // read-only
bash.mount(host, vfs, true)                        // writable opt-in

Python:

# Before: 6 verbose kwargs
Bash(mount_real_readonly_at=[("/host", "/vfs")])

# After: unified mounts list
Bash(mounts=[{"host_path": "/host", "vfs_path": "/vfs"}])           # read-only
Bash(mounts=[{"host_path": "/host", "vfs_path": "/vfs", "writable": True}])

# Before: mount_text tuples
Bash(mount_text=[("/path", "content")])

# After: files dict
Bash(files={"/path": "content"})

Test plan

  • All Rust mount tests pass (24 realfs + 7 live mount + 3 CLI)
  • Python tests updated: files dict, mounts list, read-only default, writable, live mount/unmount
  • JS tests updated: mount()/unmount() runtime methods
  • New test_bash_mounts_readonly_by_default verifies safe default
  • Type stubs (_bashkit.pyi) updated
  • cargo check, cargo fmt, ruff check, ruff format all clean
  • Python README updated
  • Specs 003-vfs and 012-maintenance updated

chaliy added 5 commits April 8, 2026 03:54
Rename MountConfig.readOnly → writable (default false) so mounts are
safe-by-default. Callers must explicitly pass writable: true to enable
host writes, instead of remembering to pass readOnly: true for safety.
Align both bindings to the same conceptual mount API:
- files: dict/record for in-memory text files (writable)
- mounts: list/array of {host_path, vfs_path?, writable?} (read-only default)
- mount()/unmount() runtime methods on all bindings

Python: replace 6 mount kwargs with files dict + mounts list,
rename FileSystem.real(readwrite=) to writable=.
JS: rename mountReal() to mount().

Add binding parity requirement to spec 003-vfs and maintenance
checklist to spec 012-maintenance.
- Update _bashkit.pyi stubs to match new files/mounts API
- Rename readwrite → writable in FileSystem.real stub
- Add test_bash_mounts_readonly_by_default verifying safe default
- Add tests for missing host_path and non-dict mount entries
- Remove unused py parameter from parse_mounts
@chaliy chaliy merged commit cc22d17 into main Apr 8, 2026
27 checks passed
@chaliy chaliy deleted the claude/mounts-readonly-default-58xnr branch April 8, 2026 05:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant