attnmd 0.3.5 → 0.4.1

package/README.md

@@ -1,46 +1,111 @@
 <p align="center">
   <h1 align="center">attn</h1>
   <p align="center">
-    A markdown viewer for people who live in the terminal.<br>
-    One command. Native window. No Electron.
+    Read markdown beautifully. Review it together.<br>
+    Native window. End-to-end encrypted collaboration. No Electron.
   </p>
 </p>
 
 <p align="center">
+  <a href="#collaboration">Collaboration</a> ·
   <a href="#install">Install</a> ·
-  <a href="https://github.com/lightsofapollo/attn/issues">Issues</a> ·
-  <a href="#contributing">Contributing</a>
+  <a href="#usage">Usage</a> ·
+  <a href="https://github.com/lightsofapollo/attn/issues">Issues</a>
 </p>
 
 ---
 
 <p align="center">
-  <img src="assets/hero.png" alt="attn showing markdown with checkboxes, code, and a file tree" width="720">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://media.githubusercontent.com/media/lightsofapollo/attn/main/site/static/screenshots/collab-dark.png">
+    <img src="https://media.githubusercontent.com/media/lightsofapollo/attn/main/site/static/screenshots/collab-light.png" alt="attn showing a shared markdown review with comments, suggestions, and a collaborator cursor" width="860">
+  </picture>
 </p>
 
 ```bash
 attn .
 ```
 
-That's it. A native window opens with your project's markdown rendered beautifully — with live reload, a file tree, tabs, and a built-in editor. No config, no browser, no 200MB runtime.
+attn opens your markdown in a native desktop window with a file tree, tabs,
+live reload, and a real editor. When a document needs feedback, hit Share and
+send an invite link. Reviewers can comment, suggest edits, and co-edit from the
+same markdown surface.
+
+No account. No browser tab. No Electron runtime. The review relay only sees
+encrypted bytes.
 
 ## Why attn?
 
-Most markdown previewers are either browser tabs you have to manually refresh, or Electron apps that eat your RAM for breakfast.
+Markdown usually lives in your repo, but review often moves somewhere else:
+screenshots, pasted docs, stale exported PDFs, or a SaaS editor with a copy of
+your source.
+
+attn keeps the source of truth local and makes review a layer over the file you
+already have. You get a focused reader, a capable editor, and an encrypted
+review room without changing how your project is organized.
+
+## Features
+
+- **Beautiful markdown rendering** - readable line length, careful typography,
+  syntax-highlighted code, tables, task lists, math, and Mermaid diagrams.
+- **Live reload** - save in Vim, VS Code, Zed, or any editor and the native
+  window updates immediately.
+- **Built-in editor** - toggle a ProseMirror editor with `Cmd+E` when you want
+  to edit in place.
+- **Interactive checkboxes** - click a `- [ ]` task and attn writes the change
+  back to the file.
+- **Project file tree** - browse folders, lazy-load large repos, and jump to
+  files with fuzzy search.
+- **Tabs and project switching** - keep multiple files open and move between
+  remembered workspaces.
+- **Native media preview** - images, video, and audio open alongside markdown.
+- **Light and dark themes** - paper-and-ink light mode plus a low-glare dark
+  mode.
+- **Single-instance CLI** - run `attn` from many terminals; one daemon receives
+  new files as tabs.
+
+## Collaboration
+
+attn's review flow is built for markdown that should stay private and local.
+
+- **Share in one click** - use the Share button, the breadcrumb/share menu, or
+  `Cmd+Shift+S` to create a review room for the active markdown file.
+- **Encrypted invite links** - send an `attn://review/...#key=...` link or the
+  generated `npx attnmd ...` command. The room key is in the invite fragment,
+  not on the relay.
+- **Comments and suggestions** - reviewers anchor feedback to selected text;
+  suggestions appear beside the document with Accept/Reject actions.
+- **Live cursors and co-editing** - connected reviewers show up in the document
+  and sidebar so you can see where people are reading or editing.
+- **Hybrid transport** - attn uses direct peer-to-peer collaboration when it can
+  and falls back to the encrypted relay when it cannot.
+- **Folder share** - share a directory to publish snapshots for every markdown
+  file under it; newly added markdown files are picked up by the watcher.
+
+Owner flow:
+
+```bash
+attn path/to/docs
+# In the app: Share, or Cmd+Shift+S
+```
 
-attn is a **single <20MB binary**. It forks to background as a daemon, opens a native macOS window, and watches your files. Edit in Vim, VS Code, whatever — attn reloads instantly. Open another file? It joins the same window as a tab.
+CLI share flow:
+
+```bash
+attn review share path/to/docs
+```
 
-**What you get:**
+Reviewer flow:
 
-- **Live reload** — save a file, see the change. No refresh button.
-- **Interactive checkboxes** — click a `- [ ]` task and it writes back to the file.
-- **Built-in editor** — hit `Cmd+E` to toggle a full ProseMirror editor with syntax highlighting, math, and mermaid diagrams.
-- **File tree + fuzzy search** — browse your project with `Cmd+P`. Lazy-loads folders so it's fast on huge repos.
-- **Tabs + projects** — open multiple files, switch between projects with `Cmd+;`. attn remembers your workspaces.
-- **Mermaid diagrams** — flowcharts, sequence diagrams, and more render inline from fenced code blocks.
-- **Media support** — images (with zoom/pan), video, and audio play natively.
-- **Paper & ink themes** — warm parchment light theme by default, cool dark theme with `--dark`.
-- **Single instance** — run `attn` from ten terminals. One daemon, one window, new tab each time.
+```bash
+attn review join 'attn://review/<room-id>#key=<secret>'
+```
+
+For headless reviewers or agents:
+
+```bash
+attn review join 'attn://review/<room-id>#key=<secret>' --as-agent reviewer
+```
 
 ## Install
 
@@ -58,20 +123,15 @@ npx attnmd
 npm install -g attnmd && attn
 ```
 
-### From source (crates.io)
-
-```bash
-cargo install attn
-```
-
-### From source (git)
+### From source
 
 ```bash
 git clone https://github.com/lightsofapollo/attn.git
-cd attn && cargo install --path .
+cd attn
+cargo install --path .
 ```
 
-Requires Rust 1.85+. For npm installs, Node 18+ is required.
+Requires Rust 1.85+. npm installs require Node 18+.
 
 ## Usage
 
@@ -80,17 +140,28 @@ attn                     # open current directory
 attn README.md           # open a file
 attn ~/projects/myapp    # open a project
 attn --dark              # force dark mode
-attn --status todo.md    # print task progress: "3/5 tasks complete"
+attn --status todo.md    # print task progress, e.g. "3/5 tasks complete"
 attn --json spec.md      # dump document structure as JSON
 ```
 
+### Review CLI
+
+```bash
+attn review share docs/                         # share a file or folder
+attn review join 'attn://review/...'            # open/join through the app
+attn review join 'attn://review/...' --as-agent reviewer
+attn review list-agents
+attn review whoami
+```
+
 ### Keyboard shortcuts
 
 | Shortcut | Action |
 |---|---|
 | `Cmd+P` | Fuzzy file search |
 | `Cmd+E` | Toggle editor |
-| `Cmd+F` | Find & replace |
+| `Cmd+F` | Find and replace |
+| `Cmd+Shift+S` | Share for review |
 | `Cmd+;` | Switch project |
 | `Cmd+W` | Close tab |
 | `Cmd+Tab` / `Cmd+Shift+Tab` | Navigate tabs |
@@ -100,37 +171,60 @@ attn --json spec.md      # dump document structure as JSON
 
 ## How it works
 
-The Svelte 5 frontend is compiled by Vite and **embedded into the Rust binary** at build time. No bundled web server, no extracted assets — it's a single self-contained executable.
+The Svelte 5 frontend is compiled by Vite and embedded into the Rust binary at
+build time. There is no bundled web server and no extracted asset directory at
+runtime.
+
+On first launch, attn forks a daemon to the background. The daemon opens a
+native window via [wry](https://github.com/tauri-apps/wry), watches your files,
+and listens on a Unix socket. Later `attn` calls connect to that socket and
+open new tabs in the existing window. If the binary changes after a rebuild,
+the old daemon is replaced automatically.
 
-First launch forks a daemon to the background. The daemon opens a native window via [wry](https://github.com/tauri-apps/wry) (the same webview engine behind Tauri) and listens on a Unix socket. Subsequent `attn` calls connect to the socket and open new tabs in the existing window. If the binary changes (you rebuild), the old daemon is automatically replaced.
+Collaboration is layered on top of the local file model. The owner shares a
+snapshot graph and review event log over an end-to-end encrypted room. The
+relay handles discovery, mailbox fallback, and presence transport, but it does
+not receive plaintext markdown or comments.
 
 ```
 src/
   main.rs       CLI, native window, keyboard shortcuts
   daemon.rs     Unix socket IPC, single-instance daemon
   watcher.rs    File system monitoring with debouncing
-  markdown.rs   Structure extraction (tasks, phases, file refs)
-  ipc.rs        Webview ↔ Rust messaging
-  files.rs      File tree, media type detection
+  markdown.rs   Structure extraction
+  ipc.rs        Webview <-> Rust messaging
+  files.rs      File tree and media type detection
   projects.rs   Project registry
+  review/       Encrypted review rooms, anchors, transport, apply flow
 
 web/src/        Svelte 5 frontend
-web/styles/     Tailwind CSS
+relay/          Cloudflare Worker relay for encrypted review traffic
+site/           Public marketing site
 ```
 
-## Contributing
+## Development
 
 ```bash
 task dev                              # Vite HMR + Rust in foreground
-task dev ATTN_PATH=path/to/file.md    # Open a specific file
+task dev ATTN_PATH=path/to/file.md    # open a specific file
+```
+
+Builds:
+
+```bash
+scripts/build.sh            # debug build
+scripts/build.sh release    # release build with devtools/screenshots
+scripts/build.sh prod       # production release build
 ```
 
-The `task dev` command starts Vite for hot module replacement and runs the Rust binary in foreground mode, pointed at the Vite dev server.
+Useful gates:
 
 ```bash
-scripts/build.sh            # Debug build
-scripts/build.sh release    # Release build
-scripts/build.sh prod       # Production build
+npm run check --prefix web
+npm test --prefix web
+cargo test
+npm test --prefix relay
+npm run build --prefix site
 ```
 
 ## License

package/bin/attn.js

@@ -1,11 +1,14 @@
 #!/usr/bin/env node
 
 const {
+  accessSync,
   chmodSync,
+  constants: fsConstants,
   createWriteStream,
   existsSync,
   mkdirSync,
   readFileSync,
+  realpathSync,
   renameSync,
   rmSync,
   symlinkSync,
@@ -59,6 +62,18 @@ async function main() {
   const version = packageJson.version;
   const headless = isHeadlessInvocation(args);
 
+  // Prefer a natively-installed `attn` only when it matches this npm
+  // package. `npx attnmd@<version>` must not silently hand off to an older
+  // Homebrew/cargo/alias binary whose review protocol may be incompatible.
+  const nativeBinary = findNativeBinary(version);
+  if (nativeBinary) {
+    if (process.env.ATTN_DEBUG_LAUNCHER) {
+      console.error(`attn: using native binary ${nativeBinary}`);
+    }
+    run(nativeBinary, args);
+    return;
+  }
+
   let appPath = null;
   if (process.platform === "darwin") {
     try {
@@ -69,7 +84,8 @@ async function main() {
   }
 
   if (!appPath) {
-    if (!existsSync(runtimeBinaryPath)) {
+    if (!isExpectedBinaryVersion(runtimeBinaryPath, version)) {
+      safeRemove(runtimeBinaryPath);
       await ensureRuntimeBinary(version);
     }
     if (!existsSync(runtimeBinaryPath)) {
@@ -99,13 +115,16 @@ async function main() {
 }
 
 async function resolveAppPath(version) {
-  const globalApp = findGlobalAppInstall();
+  const globalApp = findGlobalAppInstall(version);
   if (globalApp) {
     return globalApp;
   }
 
   const managedVersionApp = join(managedAppsRoot, version, "attn.app");
-  if (existsSync(managedVersionApp)) {
+  if (
+    existsSync(managedVersionApp) &&
+    isExpectedBinaryVersion(join(managedVersionApp, "Contents", "MacOS", "attn"), version)
+  ) {
     ensureCurrentAppLink(managedVersionApp);
     return managedVersionApp;
   }
@@ -137,19 +156,158 @@ async function ensureRuntimeBinary(version) {
   console.error(`attn: installed runtime binary ${runtimeBinaryPath}`);
 }
 
-function findGlobalAppInstall() {
+function findGlobalAppInstall(version) {
   const candidates = [
     "/Applications/attn.app",
     join(userHome, "Applications", "attn.app"),
   ];
   for (const candidate of candidates) {
-    if (existsSync(candidate)) {
+    const binary = join(candidate, "Contents", "MacOS", "attn");
+    if (existsSync(candidate) && isExpectedBinaryVersion(binary, version)) {
       return candidate;
     }
   }
   return null;
 }
 
+/**
+ * Locate an already-installed `attn` we can hand off to instead of
+ * downloading. Priority:
+ *   1. $ATTN_BIN explicit override
+ *   2. `attn` on PATH (via `command -v`)
+ *   3. The ~/.local/bin alias this launcher installs on first run
+ *   4. Common manual / package-manager install dirs (Homebrew, cargo)
+ *
+ * Each candidate is validated by `isUsableNativeBinary`, which rejects
+ * anything inside this npm package (so a global `npm i -g attn` symlink,
+ * whose realpath points back at bin/attn.js, can't cause infinite
+ * recursion).
+ */
+function findNativeBinary(version) {
+  const candidates = [];
+
+  if (process.env.ATTN_BIN) {
+    candidates.push(process.env.ATTN_BIN);
+  }
+
+  const onPath = whichAttn();
+  if (onPath) {
+    candidates.push(onPath);
+  }
+
+  candidates.push(
+    installLinkPath, // ~/.local/bin/attn — the alias we install ourselves
+    "/opt/homebrew/bin/attn",
+    "/usr/local/bin/attn",
+    join(userHome, ".cargo", "bin", "attn"),
+  );
+
+  for (const candidate of candidates) {
+    if (isUsableNativeBinary(candidate, version)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+/** Resolve `attn` on PATH without throwing. Returns null when not found. */
+function whichAttn() {
+  const probe = spawnSync(
+    process.platform === "win32" ? "where" : "command",
+    process.platform === "win32" ? ["attn"] : ["-v", "attn"],
+    { encoding: "utf8", shell: process.platform !== "win32" },
+  );
+  if (probe.status !== 0 || !probe.stdout) {
+    return null;
+  }
+  const first = probe.stdout.split("\n").map((l) => l.trim()).find(Boolean);
+  return first || null;
+}
+
+/**
+ * True when `candidate` is an executable we can safely exec as a real
+ * `attn` — i.e. it exists, is executable, and (after symlink resolution)
+ * does NOT live inside this npm package. The last check is the recursion
+ * guard: a global `npm i -g attn` makes `attn` on PATH a symlink to
+ * `<package>/bin/attn.js`; handing off to that would re-enter this script
+ * forever.
+ */
+function isUsableNativeBinary(candidate, version) {
+  if (!candidate) return false;
+  try {
+    accessSync(candidate, fsConstants.X_OK);
+  } catch {
+    return false;
+  }
+  let resolved;
+  try {
+    resolved = realpathSync(candidate);
+  } catch {
+    return false;
+  }
+  // Recursion guard: never hand off to another copy of THIS launcher.
+  // Two ways that happens:
+  //   1. The candidate resolves to this exact file (a symlink to it).
+  //   2. A global `npm i -g attn` makes `attn` on PATH a symlink to some
+  //      package's `bin/attn.js`; any `.js` is a node launcher, not a
+  //      native binary, so reject it.
+  // A compiled binary under this repo's `target/` (dev builds) is fine —
+  // it can't re-enter this script — so we deliberately DON'T reject the
+  // whole package dir, only the launcher itself + the `bin/` dir + `.js`.
+  try {
+    if (resolved === realpathSync(__filename)) return false;
+  } catch {
+    /* __filename always resolves; ignore */
+  }
+  if (resolved.endsWith(".js")) return false;
+  const binDirReal = (() => {
+    try {
+      return realpathSync(join(packageDir, "bin"));
+    } catch {
+      return join(packageDir, "bin");
+    }
+  })();
+  if (resolved.startsWith(binDirReal + "/") || resolved === binDirReal) {
+    return false;
+  }
+  return isExpectedBinaryVersion(resolved, version);
+}
+
+function isExpectedBinaryVersion(binary, version) {
+  if (!binary || !existsSync(binary)) {
+    return false;
+  }
+  if (process.env.ATTN_SKIP_NATIVE_VERSION_CHECK === "1") {
+    return true;
+  }
+  const actual = readBinaryVersion(binary);
+  const ok = actual === version;
+  if (!ok && process.env.ATTN_DEBUG_LAUNCHER) {
+    const label = actual ? `version ${actual}` : "unknown version";
+    console.error(`attn: skipping ${binary} (${label}; need ${version})`);
+  }
+  return ok;
+}
+
+function readBinaryVersion(binary) {
+  const result = spawnSync(binary, ["--version"], {
+    encoding: "utf8",
+    timeout: 2000,
+  });
+  if (result.error || result.status !== 0) {
+    return null;
+  }
+  const output = `${result.stdout || ""}\n${result.stderr || ""}`;
+  const match = output.match(/\b\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?\b/);
+  return match ? match[0] : null;
+}
+
+function safeRemove(path) {
+  if (existsSync(path)) {
+    rmSync(path, { recursive: true, force: true });
+  }
+}
+
 function ensureCurrentAppLink(appPath) {
   mkdirSync(managedRoot, { recursive: true });
   try {
@@ -267,6 +425,9 @@ if [ ! -e "$APP_LINK" ]; then
 fi
 BINARY="$APP_LINK/Contents/MacOS/attn"
 HEADLESS=0
+if [ "\${1:-}" = "review" ]; then
+  HEADLESS=1
+fi
 for arg in "$@"; do
   case "$arg" in
     --status|--json|--check|--info|--eval|--click|--wait-for|--query|--fill)
@@ -365,7 +526,7 @@ function resolvePathArgs(args) {
 }
 
 function isHeadlessInvocation(args) {
-  return args.some((arg) => HEADLESS_FLAGS.has(arg));
+  return args[0] === "review" || args.some((arg) => HEADLESS_FLAGS.has(arg));
 }
 
 function run(cmd, args) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "attnmd",
-  "version": "0.3.5",
+  "version": "0.4.1",
   "description": "A beautiful markdown viewer that launches from the CLI",
   "license": "MIT",
   "repository": {