feat(desktop): add macOS Tauri app with bundled Node runtime

Ship a desktop MVP that stages embedded Node + CodeDelta server, serves the
existing web UI on a single port, and wraps it in Tauri with single-instance
and lifecycle management. Includes staging script, CI workflow, boot screen,
and docs.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: heqikai

.github/workflows/desktop-macos.yml

@@ -0,0 +1,45 @@
+name: Desktop (macOS)
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+    paths:
+      - 'apps/desktop/**'
+      - 'apps/web/**'
+      - 'packages/**'
+      - 'scripts/desktop-stage.mjs'
+      - 'src/**'
+
+jobs:
+  build-macos:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: npm
+
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@1.88.0
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Stage desktop runtime
+        run: npm run stage:desktop
+
+      - name: Build desktop app
+        run: npm run build:app -w @codedelta/desktop
+
+      - name: Upload dmg artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: codedelta-macos-dmg
+          path: |
+            apps/desktop/src-tauri/target/release/bundle/dmg/*.dmg
+          if-no-files-found: error
+
+      # Optional: add APPLE_CERTIFICATE / notarytool steps when signing secrets are configured.

.gitignore

@@ -49,6 +49,15 @@ npm-debug.log*
 
 # CodeDelta local cache (repos, snapshots, settings)
 .codedelta/
+.codedelta-desktop-smoke/
+
+# Desktop bundled runtime (generated by npm run stage:desktop)
+apps/desktop/src-tauri/resources/runtime/
+apps/desktop/src-tauri/target/
+apps/desktop/src-tauri/.cargo-home/
+
+# Local-only docs (not for GitHub)
+docs/codedelta/wechat-article-codedelta.md
 
 test_frameworks
 

README.md

@@ -193,6 +193,7 @@ packages/
   codedelta-trace-engine/
   codedelta-provider-runtime/
 apps/web/                     # React UI
+apps/desktop/                 # macOS desktop shell (Tauri 2)
 ```
 
 Roadmap and deferred work: [docs/codedelta/ROADMAP.md](docs/codedelta/ROADMAP.md).
@@ -205,6 +206,34 @@ Roadmap and deferred work: [docs/codedelta/ROADMAP.md](docs/codedelta/ROADMAP.md
 - UI: tables/lists (no full graph canvas yet)
 - Symbol click opens **file** diff, not symbol-to-hunk mapping
 
+## Desktop (macOS)
+
+CodeDelta ships a **macOS desktop app** (`apps/desktop`) that bundles Node 20 and the API server — no separate Node install required for end users.
+
+**Requirements to build:** macOS (arm64 or x64), [Xcode Command Line Tools](https://developer.apple.com/xcode/resources/), [Rust 1.88+](https://rustup.rs/) (use `rustup`; Homebrew `cargo` alone may be too old), and repo dev dependencies (`npm ci`).
+
+```bash
+# One-time: stage embedded Node + server runtime (~200MB under apps/desktop/src-tauri/resources/runtime/)
+npm run stage:desktop
+
+# Build .app + .dmg (unsigned; Gatekeeper may prompt on first open)
+npm run build:desktop
+
+# Dev: API + Vite + Tauri window (uses localhost:5173 + :3847, not bundled runtime)
+npm run dev:desktop
+```
+
+**Runtime data:** `~/Library/Application Support/CodeDelta` (repos, snapshots, settings).
+
+**Git:** must be on `PATH` for import/compare/trace (the app shows a banner if `git` is missing).
+
+| Variable | Desktop default | Meaning |
+|----------|-----------------|---------|
+| `CODEDELTA_CACHE_DIR` | `~/Library/Application Support/CodeDelta` | Cache root (set by Tauri) |
+| `CODEDELTA_MONOREPO_ROOT` | bundled `runtime/app` | CodeGraph dist root |
+| `CODEDELTA_STATIC_DIR` | bundled `runtime/web-dist` | Web UI static files |
+| `CODEDELTA_DESKTOP` | `1` | Desktop mode flag |
+
 ## Development
 
 ```bash
@@ -222,6 +251,9 @@ Environment variables:
 |----------|---------|---------|
 | `CODEDELTA_CACHE_DIR` | `.codedelta/` | Cache root |
 | `CODEDELTA_PORT` | `3847` | API port |
+| `CODEDELTA_MONOREPO_ROOT` | (monorepo root) | CodeGraph dist root; required for desktop bundle |
+| `CODEDELTA_STATIC_DIR` | — | Serve web UI from this directory (desktop production) |
+| `CODEDELTA_DESKTOP` | — | When `1`, default cache dir on macOS is Application Support |
 | `CODEDELTA_SNAPSHOT_TIMEOUT_MS` | `120000` | Snapshot build timeout |
 | `CODEDELTA_SNAPSHOT_MAX_NODES` | `50000` | Snapshot node cap |
 

apps/desktop/.gitignore

@@ -0,0 +1,4 @@
+/target/
+/app-icon.png
+/app-icon.ppm
+/.cargo-home/

apps/desktop/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@codedelta/desktop",
+  "version": "0.1.0",
+  "private": true,
+  "description": "CodeDelta desktop shell (macOS, Tauri 2)",
+  "scripts": {
+    "dev": "PATH=\"$HOME/.cargo/bin:$PATH\" tauri dev",
+    "build:app": "PATH=\"$HOME/.cargo/bin:$PATH\" tauri build"
+  },
+  "devDependencies": {
+    "@tauri-apps/cli": "^2.5.0"
+  },
+  "license": "MIT"
+}