Merge pull request #9 from crimsonsunset/dev-rebased

feat: land fork on main — machine-scoped routing, web admin, remote MCP

Author: crimsonsunset

.env.example

@@ -0,0 +1,15 @@
+# Copy to `.env` in the repo root (gitignored). Used by remote tunnel smoke scripts
+# and Playwright admin tests — never commit real values.
+
+# Cloudflare Access service token (Zero Trust → Access → Service Auth)
+MCPMUX_CF_ACCESS_CLIENT_ID=
+MCPMUX_CF_ACCESS_CLIENT_SECRET=
+
+# Optional tunnel hostnames for `pnpm remote:smoke`
+MCPMUX_REMOTE_GATEWAY_URL=https://mcp.example.com
+MCPMUX_REMOTE_ADMIN_URL=https://mux.example.com
+
+# Playwright admin parity against loopback admin with CF trust enabled
+# MCPMUX_ADMIN_CF_JWT=
+# MCPMUX_ADMIN_CF_TRUST_ENABLED=1
+# MCPMUX_ADMIN_BASE_URL=http://localhost:45819

.github/actions/install-linux-deps/action.yml

@@ -13,18 +13,30 @@ runs:
   using: composite
   steps:
     # Cache apt packages to avoid re-downloading on every run
+    # The runner image ships an apt index from its build date, and
+    # cache-apt-pkgs-action's own refresh (update_apt_lists_if_stale) is a
+    # no-op outside nektos/act -- it guards on ACT=true. A stale index names
+    # .debs that Ubuntu has since superseded and dropped from the pool, so the
+    # install 404s; the action then caches the empty result instead of failing,
+    # and every later run restores that as a hit and skips installing at all.
+    - name: Refresh apt lists
+      shell: bash
+      run: sudo apt-get update
+
+    # Pinned to a SHA: `@latest` is a moving tag, so a broken upstream release
+    # (e.g. v1.6.2) would otherwise roll straight into CI unreviewed.
     - name: Cache apt packages (base)
-      uses: awalsh128/cache-apt-pkgs-action@latest
+      uses: awalsh128/cache-apt-pkgs-action@553a35bb8ebd9fcabcb1c9451aa4c98e1b4ca8a9 # v1.6.3
       with:
         packages: build-essential pkg-config libglib2.0-dev libgtk-3-dev libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf libsecret-1-dev libfuse2
-        version: 1.1
+        version: 1.2
 
     - name: Cache apt packages (E2E)
       if: ${{ inputs.e2e == 'true' }}
-      uses: awalsh128/cache-apt-pkgs-action@latest
+      uses: awalsh128/cache-apt-pkgs-action@553a35bb8ebd9fcabcb1c9451aa4c98e1b4ca8a9 # v1.6.3
       with:
         packages: webkit2gtk-driver xvfb gnome-keyring gsettings-desktop-schemas dbus-x11 at-spi2-core libglib2.0-bin libwayland-server0 libwayland-client0
-        version: 1.3
+        version: 1.4
 
     # Compile gsettings schemas (required after restore from cache)
     - name: Compile gsettings schemas

.github/workflows/ci.yml

@@ -17,6 +17,7 @@ permissions:
   actions: read
   checks: write
   pull-requests: write
+  id-token: write
 
 env:
   CARGO_TERM_COLOR: always

.github/workflows/claude.yml

@@ -0,0 +1,50 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # This is an optional setting that allows Claude to read CI results on PRs
+          additional_permissions: |
+            actions: read
+
+          # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
+          # prompt: 'Update the pull request description to include a summary of changes.'
+
+          # Optional: Add claude_args to customize behavior and configuration
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://code.claude.com/docs/en/cli-reference for available options
+          # claude_args: '--allowed-tools Bash(gh pr *)'
+

.gitignore

@@ -60,6 +60,7 @@ coverage/
 # Test reports & assets
 test-results/
 playwright-report/
+.playwright-mcp/
 blob-report/
 html-report/
 tests/e2e/reports/
@@ -92,3 +93,6 @@ apps/desktop/src-tauri/target/release/bundle/
 debug/
 *.dSYM/
 
+
+# Cursor rules — symlinked from ~/.cursor/rules/projects/
+.cursor/rules/

.vscode/settings.json

@@ -6,6 +6,7 @@
     "rust-analyzer.rustfmt.extraArgs": [
         "+nightly"
     ],
+    "rust-analyzer.cargo.targetDir": true,
     "files.eol": "\n",
     "files.insertFinalNewline": true,
     "files.trimTrailingWhitespace": true,

AGENTS.md

@@ -32,6 +32,10 @@ Run everything from `mcp-mux/`:
 | `pnpm setup` | First-time dev environment setup (PowerShell on Windows). |
 | `pnpm dev` | Tauri desktop dev mode (Rust + React hot-reload). |
 | `pnpm dev:web` | Web UI only via Vite — no Rust, no Tauri shell. |
+| `pnpm dev:admin` | Full stack + web admin: `tauri dev` with admin enabled, opens browser at `:1420` once the gateway is stable. Primary dev driver. |
+| `pnpm dev:web:admin` | Browser-only admin UI; auto-starts the backend detached if it isn't already up. |
+| `pnpm dev:stop` | Quit McpMux.app and free the dev ports (`:1420`, `:45818`, `:45819`). |
+| `pnpm dev:rebuild` | Force `cargo build --workspace` (debug) without launching — recovery for stale binaries. |
 | `pnpm build` | Production Tauri build for the current platform. |
 | `pnpm validate` | Full correctness gate — runs the items below in sequence. |
 | `pnpm lint` | ESLint (recursive) + `cargo clippy --workspace -- -D warnings`. |
@@ -40,6 +44,8 @@ Run everything from `mcp-mux/`:
 | `pnpm format:check` | Formatting check (no writes). |
 | `pnpm typecheck` | Recursive TypeScript typecheck. |
 
+**Hot-reload while developing:** `pnpm dev:admin` keeps the desktop window, the `:1420` browser tab (Vite HMR), and the CF tunnel / `:45819` static UI in sync. TS/CSS changes hot-reload instantly on `:1420`; the same edits trigger `vite build --watch` to rebuild `apps/desktop/dist/` for `:45819` and remote tunnel tabs (hard-refresh those after each rebuild, ~10s). Rust changes in any workspace crate trigger `tauri dev` to recompile and restart the backend automatically. Rust is compiled, so "auto-reload" means recompile + process restart, not live patching. After a stalled restart, orphaned backend, or stale binary, recover with `pnpm dev:stop && pnpm dev:rebuild && pnpm dev:admin`. The repo's `.vscode/settings.json` sets `rust-analyzer.cargo.targetDir` so the editor's `cargo check` doesn't fight `tauri dev` over `target/` (avoids double compiles). When `.env` carries CF Access credentials the admin runs with `cf_access=true`; the dev scripts' health probes send `adminCfProbeHeaders()` so `/api/v1/health` doesn't 401. One-off production bundle: `pnpm build:web:admin`.
+
 **Before claiming a change is done**, run `pnpm validate` (or the relevant subset) — it mirrors what CI enforces.
 
 ## Testing