bookmark-bridge 0.1.0 → 0.1.2

package/README.md

@@ -1,22 +1,22 @@
 # Bookmark Bridge
 
-Lets an MCP client read and reorganize Chrome bookmarks, with every change
-recorded in git so it can be rolled back.
+An MCP client can read and reorganize your Chrome bookmarks through this.
+Every change lands in git first, so anything can be rolled back.
 
 ```
 MCP client --stdio--> bookmark-bridge --ws(127.0.0.1)-- Chrome extension --chrome.bookmarks--> Chrome
 ```
 
-The extension is the WebSocket client; it dials out because an extension cannot
-listen on a port. A second MCP process that cannot bind the port joins the first
-as a peer and relays through it, so several sessions share one browser.
+The extension dials out rather than listening, because an extension cannot open
+a port. A second MCP process that finds the port taken joins the first as a peer
+and relays through it, so several sessions share one browser.
 
 ## Install
 
-Two pieces: this server, and a Chrome extension that dials into it.
+Two pieces: this server, and the Chrome extension that dials into it.
 
-**1. Register the server with your MCP client.** It is fetched on first run; no
-Rust needed. macOS and Linux only — the server uses `flock` and POSIX file modes.
+**1. Register the server with your MCP client.** It downloads itself on first
+run, so you do not need Rust. macOS, Linux and Windows.
 
 <details open>
 <summary><b>Claude Code</b></summary>
@@ -72,19 +72,25 @@ Install the bookmark-bridge MCP server for me.
    extension from https://github.com/semanticist21/bookmark-bridge and then
    check again.
 
-It is macOS and Linux only. Do not build from source; the npx package fetches
-a prebuilt binary.
+Do not build from source; the npx package fetches a prebuilt binary.
 ```
 
 </details>
 
-Your client starts and stops the server for you; there is no daemon to run.
+Your client starts and stops it for you. Nothing to leave running. `git` must be
+on PATH — the snapshots are a real git repository.
 
 **2. Install the extension.** From the Chrome Web Store, or load `extension/`
 at `chrome://extensions` with developer mode on.
 
-That is the whole setup. The extension shows a green light in its popup once the
-two find each other.
+That is all of it. The extension's popup goes green once the two find each other.
+
+The extension sleeps when you are not using it. Chrome ends an idle service
+worker, and this one is not woken on a timer — tidying bookmarks is occasional
+work, and polling a socket nobody is using is what Manifest V3 set out to stop.
+It wakes on its own when the browser starts, when a setting changes, when you
+touch a bookmark, and when you open its popup. If an agent reports that the
+extension is not connected, clicking the toolbar icon reconnects it.
 
 <details>
 <summary>From source instead</summary>
@@ -108,26 +114,26 @@ extension's storage. `BOOKMARK_BRIDGE_PORT` changes the port.
 
 ## Safety model
 
-Three independent mechanisms, in the order they engage:
+Three mechanisms, in the order they engage.
 
 **Snapshots.** Every mutating call commits the whole tree to a git repository at
-`~/.local/state/bookmark-bridge/history` before and after the change. If the
-before-snapshot fails, the change is refused — a mutation that cannot be undone
-is not worth making. Pass `force: true` to override.
+`~/.local/state/bookmark-bridge/history`, before and after. A failed
+before-snapshot refuses the change: a mutation nobody can undo is not worth
+making. `force: true` overrides that.
 
 **Compare-and-swap.** Any operation may carry `expect: {title?, url?, parentId?}`.
-If the current value differs, that operation alone is skipped and reported with
-the actual value. This is what protects a plan from a user edit that landed
-between planning and applying.
+If the live value differs, that one operation is skipped and reported with what
+was actually there. This is what survives a user edit landing between planning
+and applying.
 
-**Drift detection.** `history_drift` compares the live tree against `agent-head`,
-the commit marking the agent's last completed operation. The difference is what
-someone else changed. The extension additionally records bookmark events tagged
-`agent` or `user`; that ledger is evidence, and the diff is the authority.
+**Drift detection.** `history_drift` diffs the live tree against `agent-head`,
+the commit marking the agent's last finished operation. Whatever differs is
+someone else's work. The extension also logs bookmark events tagged `agent` or
+`user`; that ledger is evidence, the diff is the authority.
 
 ## Known limits
 
-These are real. Read them before trusting the output.
+Read these before trusting the output.
 
 - **Reading list is invisible.** `chrome.readingList` is a separate API whose
   items never appear in the bookmark tree. Neither layer sees them.
@@ -150,12 +156,14 @@ These are real. Read them before trusting the output.
 
 ## Tests
 
-`cd mcp && cargo test` spawns the real binary, plays the extension with a
-WebSocket client holding an in-memory tree, and drives it over MCP. It covers the
-protocol handshake, compare-and-swap skipping, idempotent create, the batch size
-cap, refusing to mutate without a snapshot, restoring a deleted subtree under new
-ids, drift reporting only the user's changes, and two sessions sharing one
-extension through the peer relay.
+`cd mcp && cargo test` runs the real binary against a fake extension: a
+WebSocket client holding an in-memory tree. The destructive paths are covered
+without a browser, including restoring a deleted subtree under new ids, refusing
+to mutate when no snapshot can be taken, and two sessions sharing one extension
+through the peer relay.
+
+Two release-blocking defects came out of writing these, both invisible on a
+machine that had already been set up once.
 
 ## Tools
 
@@ -169,11 +177,11 @@ extension through the peer relay.
 
 ## Privacy
 
-The extension holds `bookmarks`, `storage` and `alarms`. It connects only to
-`127.0.0.1` and rejects WebSocket handshakes carrying an `http(s)` origin, so a
-web page cannot reach it. Nothing is sent anywhere else. The token stops a page
-from connecting; it does not stop another process on the same machine, which can
-read the token file just as easily.
+The extension holds `bookmarks` and `storage`. It connects only to
+`127.0.0.1` and turns away handshakes carrying an `http(s)` origin, so a web page
+cannot reach it. Nothing goes anywhere else. The token stops a page; it does not
+stop another process on this machine, which can read the token file just as
+easily.
 
 ## License
 

package/bin/bookmark-bridge.mjs

@@ -20,8 +20,11 @@ const TARGETS = {
   'darwin-x64': 'x86_64-apple-darwin',
   'linux-x64': 'x86_64-unknown-linux-gnu',
   'linux-arm64': 'aarch64-unknown-linux-gnu',
+  'win32-x64': 'x86_64-pc-windows-msvc',
 };
 
+const EXE = process.platform === 'win32' ? '.exe' : '';
+
 function die(message) {
   process.stderr.write(`bookmark-bridge: ${message}\n`);
   process.exit(1);
@@ -30,15 +33,13 @@ function die(message) {
 const key = `${process.platform}-${process.arch}`;
 const target = TARGETS[key];
 if (!target) {
-  die(`no prebuilt server for ${key}. The server uses flock and POSIX file modes, `
-    + `so Windows is not supported. Build from source: `
-    + `https://github.com/${REPO}`);
+  die(`no prebuilt server for ${key}. Build from source: https://github.com/${REPO}`);
 }
 
 // Cached per version, so upgrading the package fetches a matching server rather
 // than silently reusing an old one.
 const cacheDir = join(here, '..', '.bin', pkg.version);
-const binary = join(cacheDir, 'bookmark-bridge');
+const binary = join(cacheDir, `bookmark-bridge${EXE}`);
 
 async function exists(path) {
   try { await stat(path); return true; } catch { return false; }
@@ -86,7 +87,8 @@ async function install() {
     // directory.
     await rm(cacheDir, {recursive: true, force: true});
     await rename(join(staging, `bookmark-bridge-${target}`), cacheDir);
-    await chmod(binary, 0o755);
+    // Windows has no execute bit; the archive already carries it elsewhere.
+    if (process.platform !== 'win32') await chmod(binary, 0o755);
   } finally {
     await rm(staging, {recursive: true, force: true});
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bookmark-bridge",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Chrome bookmarks as MCP tools, with every change recorded in git so it can be rolled back",
   "license": "MIT",
   "repository": {
@@ -11,10 +11,22 @@
   "bin": {
     "bookmark-bridge": "bin/bookmark-bridge.mjs"
   },
-  "files": ["bin/", "README.md"],
+  "files": [
+    "bin/",
+    "README.md"
+  ],
   "engines": {
     "node": ">=18"
   },
-  "os": ["darwin", "linux"],
-  "keywords": ["mcp", "model-context-protocol", "bookmarks", "chrome"]
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "bookmarks",
+    "chrome"
+  ]
 }