75 lines
3.0 KiB
Markdown
75 lines
3.0 KiB
Markdown
# macOS Docker Client Implementation Plan
|
|
|
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
|
|
**Goal:** Build a macOS Docker client mode that exposes a local HTTP/SOCKS proxy on `127.0.0.1:8080` with a friendlier UI and a curl installer.
|
|
|
|
**Architecture:** Reuse the current Node API, React UI, subscription parser, sing-box process manager, and routing rule generator. Add `APP_MODE=client` so the same backend emits a proxy-only sing-box config without TProxy, and use a dedicated Dockerfile/compose path for Mac installation.
|
|
|
|
**Tech Stack:** Node.js ESM, React/Vite, sing-box, Docker Compose, POSIX shell, `node:test`.
|
|
|
|
---
|
|
|
|
### Task 1: Client Mode Config Contract
|
|
|
|
**Files:**
|
|
- Create: `test/server/singbox-client-mode.test.js`
|
|
- Modify: `package.json`
|
|
- Modify: `src/server/config.js`
|
|
- Modify: `src/server/singbox.js`
|
|
- Modify: `src/server/index.js`
|
|
|
|
- [ ] Add `node:test` coverage that proves `APP_MODE=client` config has `mixed-in`, no `tproxy-in`, no transparent fallback, and a VPN proxy fallback.
|
|
- [ ] Add `npm test` script.
|
|
- [ ] Add `settings.appMode`.
|
|
- [ ] Make `buildGatewayConfig()` conditionally emit client-only inbounds and route rules.
|
|
- [ ] Expose `mode` and hide irrelevant tproxy fields in public state.
|
|
|
|
### Task 2: macOS Client Docker Runtime
|
|
|
|
**Files:**
|
|
- Create: `entrypoint.client.sh`
|
|
- Create: `Dockerfile.client`
|
|
- Create: `docker-compose.client.yml`
|
|
|
|
- [ ] Add an entrypoint that starts only the Node control server.
|
|
- [ ] Add a Dockerfile that builds the Vite frontend inside Docker and installs only client runtime dependencies plus sing-box.
|
|
- [ ] Add compose with loopback-only port publishing for UI and proxy.
|
|
|
|
### Task 3: User-Friendly Client UI
|
|
|
|
**Files:**
|
|
- Create: `src/web/components/ClientOverviewPage.jsx`
|
|
- Modify: `src/web/App.jsx`
|
|
- Modify: `src/web/components/Sidebar.jsx`
|
|
- Modify: `src/web/components/Topbar.jsx`
|
|
- Modify: `src/web/components/StatusPane.jsx`
|
|
- Modify: `src/web/components/RouteChecker.jsx`
|
|
- Modify: `src/web/styles.css`
|
|
|
|
- [ ] Add a client overview with status, active server, copyable proxy URLs, and macOS setup commands.
|
|
- [ ] Hide gateway-only navigation and side status pane in client mode.
|
|
- [ ] Rename topbar brand to match current mode.
|
|
- [ ] Keep servers, logs, and settings reachable in client mode.
|
|
|
|
### Task 4: curl Installer and Docs
|
|
|
|
**Files:**
|
|
- Create: `scripts/install-macos-client.sh`
|
|
- Modify: `README.md`
|
|
- Modify: `.env.example`
|
|
|
|
- [ ] Add curl-friendly installer with Docker/Git checks and update-or-clone behavior.
|
|
- [ ] Document one-line install command and manual compose command.
|
|
- [ ] Add client mode environment examples.
|
|
|
|
### Task 5: Verification
|
|
|
|
**Commands:**
|
|
- `npm test`
|
|
- `npm run build`
|
|
- `docker compose -f docker-compose.client.yml config`
|
|
|
|
- [ ] Run all commands and fix any failures.
|
|
- [ ] Inspect the diff to confirm existing CI/runtime-base edits remain untouched.
|