@muvon/octofs 0.12.0 → 0.14.0

package/README.md

@@ -10,11 +10,11 @@
 [![MCP](https://img.shields.io/badge/MCP-2026--07--28-green.svg)](https://modelcontextprotocol.io)
 [![Version](https://img.shields.io/crates/v/octofs.svg)](https://crates.io/crates/octofs)
 
-*Standalone Rust binary that exposes filesystem tools over the Model Context Protocol. Built on `rmcp` 3.0, `tokio`, and `axum`.*
+*Standalone Rust binary that exposes filesystem tools over the Model Context Protocol. Built on `rmcp` 3.x, `tokio`, and `axum`.*
 
-[Installation](#installation) · [Quick Start](#quick-start) · [Features](#features) · [Tools Reference](#mcp-tools-reference) · [Architecture](#architecture)
+[Installation](#installation) · [Quick Start](#quick-start) · [Features](#features) · [Tools Reference](#mcp-tools-reference) · [Architecture](#architecture) · [Changelog](CHANGELOG.md)
 
-MCP Registry: [`io.github.Muvon/octofs`](https://github.com/muvon/octofs)
+MCP Registry: [`io.github.Muvon/octofs`](https://registry.modelcontextprotocol.io)
 
 </div>
 
@@ -53,9 +53,9 @@ Your AI coding assistant (Cursor, Claude, Windsurf, etc.) is smart — but it's
 | **Implementation** | Compiled Rust binary, no runtime | Python/Node script |
 | **Content Search** | Built-in search with context lines | String matching only |
 | **Batch Operations** | Atomic multi-edit on single file | One-at-a-time |
-| **Line Modes** | Hash-based (stable across edits) or number-based | Number-only |
+| **Line Addressing** | Composite `N:hh` ids — hash-verified at apply time; stale edits fail with relocation hints | Number-only |
 | **Transport** | STDIO + Streamable HTTP | STDIO only |
-| **Shell Integration** | Foreground + background process support | Limited or none |
+| **Shell Integration** | Automatic foreground-to-background handoff | Limited or none |
 | **Remote Files** | Transparent SSH/SFTP on every file tool | None |
 | **Safety** | Gitignore-aware, stale-write detection, path validation | Full filesystem access |
 
@@ -75,6 +75,25 @@ cargo install octofs
 brew install muvon/tap/octofs
 ```
 
+### npm (no Rust toolchain needed)
+
+```bash
+npx -y @muvon/octofs --version
+```
+
+The wrapper downloads the matching pre-built binary on first run. MCP config:
+
+```json
+{
+  "mcpServers": {
+    "octofs": {
+      "command": "npx",
+      "args": ["-y", "@muvon/octofs", "mcp"]
+    }
+  }
+}
+```
+
 ### Pre-built Binaries
 
 Download from [GitHub Releases](https://github.com/muvon/octofs/releases) for your platform:
@@ -88,9 +107,11 @@ Download from [GitHub Releases](https://github.com/muvon/octofs/releases) for yo
 | macOS (Intel) | `x86_64-apple-darwin` |
 | macOS (Apple Silicon) | `aarch64-apple-darwin` |
 
+Each release also ships `.mcpb` bundles for one-click install in clients that support MCP bundles (e.g. Claude Desktop).
+
 ### MCP Registry
 
-One-click install via the [MCP Registry](https://github.com/muvon/octofs) entry `io.github.Muvon/octofs`.
+Published to the [MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.Muvon/octofs`.
 
 ### From Source
 
@@ -180,7 +201,7 @@ Ask your AI assistant to:
 - **Delete** — Remove a file (recoverable via undo)
 - **Undo** — Revert last edit (up to 10 undo levels per file, in-memory)
 - **Batch Edit** — Perform multiple insert/replace operations atomically on a single file
-- **Stale-Write Protection** — Edits fail fast if the file changed on disk since it was last viewed (external-edit detection, like an IDE's "file changed on disk" guard)
+- **Stale-Write Protection** — Every edit target's `N:hh` id is verified against the file at apply time; a stale id fails with the current content and where it moved, instead of editing the wrong line
 
 ### 🔍 Code Intelligence
 
@@ -190,7 +211,7 @@ Ask your AI assistant to:
 ### 🖥️ Shell & System
 
 - **Command Execution** — Run shell commands with output capture
-- **Background Processes** — Run long commands in background, get PID for later management
+- **Background Processes** — Long commands automatically continue in background with completion notifications
 - **Working Directory** — Set/get/reset working directory context for operations
 
 ---
@@ -279,7 +300,8 @@ octofs mcp --path ssh://deploy@example.com/var/www/app --ssh-key ~/.ssh/id_ed255
 view path="ssh://deploy@example.com/etc/nginx/nginx.conf"
 ```
 
-- **Authentication** — fully automatic, like OpenSSH, honoring `~/.ssh/config`: the agent your config names for the host (`IdentityAgent`, e.g. 1Password) or `$SSH_AUTH_SOCK`, then key files — `--ssh-key` if given, the host's `IdentityFile` entries, then the defaults in `~/.ssh` (`id_ed25519`, `id_ecdsa`). If plain `ssh host` works on your machine, octofs works too — nothing to configure. Passphrase-protected key files are not supported directly; use an agent instead.
+- **OpenSSH config** — host aliases are resolved through the local OpenSSH config (including `Include` and `Match`) and honor `HostName`, `User`, `Port`, and a single `ProxyJump`. Explicit URL values win, so both `ssh://dev/path` and `ssh://user@example.com:2222/path` work as expected. Multi-hop `ProxyJump` and `ProxyCommand` routing are rejected with a clear error.
+- **Authentication** — uses the host's `IdentityAgent` (e.g. 1Password) or `$SSH_AUTH_SOCK`, then key files — `--ssh-key` if given, the host's `IdentityFile` entries, then the defaults in `~/.ssh` (`id_ed25519`, `id_ecdsa`). Passphrase-protected key files are not supported directly; use an agent instead.
 - **RSA keys are not supported** — the Rust `rsa` crate has an unfixed timing side-channel (Marvin attack, [RUSTSEC-2023-0071](https://rustsec.org/advisories/RUSTSEC-2023-0071)), so octofs is built without RSA entirely. Use an ed25519 key instead (`ssh-keygen -t ed25519`); ecdsa also works. RSA-only setups fail with a clear error naming the key.
 - **Host keys** — verified against `~/.ssh/known_hosts` with the OpenSSH `accept-new` policy: unknown hosts are recorded on first use, a changed key fails closed.
 - **`--ssh-timeout SECS`** — connection timeout (default 30). Connections are pooled per host, kept alive with transport keepalives, and reconnected automatically if they drop.
@@ -450,17 +472,21 @@ the file). `append_line` positions the copy in the target: `0` = beginning,
 
 ### `shell` — Execute commands
 
-**Foreground:**
+Commands start in the foreground and return their output normally when they
+finish within about 10 seconds:
+
 ```json
 {"command": "cargo test"}
 {"command": "cd foo && cargo build"}
 ```
 
-**Background:**
-```json
-{"command": "python -m http.server 8000", "background": true}
-// Returns PID; the response includes the platform-specific kill command
-```
+If a command is still running at that boundary, the same process continues in
+the background. The response returns its PID and linked output resource, and a
+completion notification arrives when it exits. There is no `background` flag
+and the command is never killed or restarted during the handoff. Multiple
+distinct commands may run concurrently, including from the same working
+directory. An exact duplicate command in the same working directory is rejected
+while the first copy is still running.
 
 > On Windows, shutdown cleanup terminates only direct child processes (no Unix
 > process-group semantics); use `taskkill /PID <pid> /T` for process trees.
@@ -516,7 +542,7 @@ octofs/
 
 **Key design decisions:**
 
-- **rmcp SDK** — Official Rust MCP SDK (`rmcp` 3.0) for protocol handling
+- **rmcp SDK** — Official Rust MCP SDK (`rmcp` 3.x) for protocol handling
 - **Tokio** — Async runtime; all file I/O uses `tokio::fs`, never blocking `std::fs`
 - **File locking** — Per-file `tokio::sync::Mutex` prevents concurrent write conflicts
 - **Undo history** — Up to 10 snapshots per file, in-memory (lost on restart)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@muvon/octofs",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Standalone MCP filesystem tools server \u2014 view, edit, shell, workdir.",
   "mcpName": "io.github.Muvon/octofs",
   "bin": {