Clarify active Windows client architecture

2026-07-07 21:19:41 +03:00
parent a0f41baa36
commit 59f2264a2e
55 changed files with 19554 additions and 8 deletions
--- a/docs/goals/windows-modular-client/EVIDENCE.md
+++ b/docs/goals/windows-modular-client/EVIDENCE.md
--- a/docs/goals/windows-modular-client/GOAL.md
+++ b/docs/goals/windows-modular-client/GOAL.md
@@ -0,0 +1,16 @@
+# Goal: Windows Tauri Proxy Client
+
+Use Krypton Execution to execute `docs/goals/windows-modular-client/PLAN.md`.
+
+Core rules:
+- Treat `PLAN.md` as the source plan.
+- Preserve intent, ownership, contract, cutover, evidence, and kill criteria.
+- Build a separate Tauri 2 Windows desktop app under `apps/windows-client`.
+- Do not implement Windows by extending the current Node gateway/client server.
+- Keep Control App, Proxyfier Layer, and Local sing-box separately installable and operable.
+- Make external proxy target + ProxiFyre profile apply the MVP.
+- Keep Local sing-box optional; it must not be required for external target profiles.
+- Keep generated ProxiFyre and sing-box configs derived from source models.
+- Capture acceptance evidence from the target user's perspective and record it in `EVIDENCE.md`.
+- Say "implemented but unproven" if Windows-only privileged evidence cannot be captured.
+
--- a/docs/goals/windows-modular-client/PLAN.md
+++ b/docs/goals/windows-modular-client/PLAN.md
@@ -0,0 +1,506 @@
+# Windows Tauri Proxy Client Implementation Plan
+
+**Intent:** Build a separate Windows desktop proxy management app using Tauri 2, React, TypeScript, and Rust. The app manages three independent components: Control App, Proxyfier Layer, and optional Local sing-box.
+**Current Behavior:** The repo contains a gateway/client Node + React web application and planning documents for a Windows mode inside that app. A newer product/technology brief now targets a standalone Windows desktop utility instead of extending the existing web control panel.
+**Expected Outcome:** A compact Windows desktop utility lets the user configure app-level proxy routing through external SOCKS5/HTTP targets first, then optionally install and use local sing-box. The app remains useful when sing-box is absent.
+**Target-Perspective Output:** A Windows user opens the desktop app, sees Overview, Profiles, Targets, Components, and Logs, adds Discord or another process/folder/exe profile, selects an external proxy target, applies changes to the proxyfier layer, and sees component status plus recent activity. Later, installing Local sing-box adds a local target without changing the profile model.
+**Truth Owner:** Source configuration lives in the Tauri app's Rust domain model and JSON files under `C:\ProgramData\VpnProxy`. Generated ProxiFyre and sing-box configs are derived artifacts. Privileged install/service operations are owned by explicit helper/installer flows, not by React UI state.
+**Contract Boundary:** React UI calls typed Tauri commands. Tauri Rust backend validates and persists profiles/targets/components. Proxy routing is behind a `ProxyRouterAdapter` boundary, with ProxiFyre as the first adapter. Privileged operations go through explicit helper/install commands returning structured JSON.
+**Cutover:** Supersede the prior Node `APP_MODE=windows` implementation direction. Keep existing gateway/client code intact. New Windows work lives under a separate Tauri app slice.
+**Displaced Path:** The old plan to add Windows mode into `src/server`/`src/web` is demoted to historical context. Do not add a third app mode to the current Node server for this product.
+**Value Density:** The smallest high-value slice is the desktop app MVP with external SOCKS5 target + ProxiFyre profile apply. Local sing-box is optional and comes after the proxyfier MVP is proven.
+**Evidence Gate:** Evidence must include target-perspective app proof: built Tauri app or dev window screenshot/state, generated proxyfier config artifact, mocked or real helper response, and manual Windows checklist when privileged components are involved.
+**Acceptance Evidence:** Automated tests pass for Rust/TypeScript domain logic, app build succeeds, the MVP can create a profile and generate/apply ProxiFyre config against an external target, and Windows manual evidence proves independent component behavior.
+**Evidence Lane:** Record command output, app screenshots/state payloads, generated configs, and manual verification in `docs/goals/windows-modular-client/EVIDENCE.md`.
+**Kill Criteria:** No Windows implementation inside current Node gateway/client server; no mandatory sing-box dependency; no generated config as source truth; no hidden installation during profile apply; no direct UI parsing of raw PowerShell/stdout.
+**Architecture Slice:** New standalone Tauri app under `apps/windows-client`, plus docs updates that point from older Windows plans to this plan.
+**Plan Review Gate:** Requires PRE review before implementation execution.
+
+## Source Brief
+
+Product and technology source brief:
+
+- `docs/windows-client-product-tech-brief.md`
+
+This plan turns that brief into an execution-ready implementation sequence.
+
+## Outcome Contract
+
+Plan title: Windows Tauri Proxy Client
+
+Intent: Build a native-feeling Windows utility that manages app-level proxy routing while keeping Control App, Proxyfier Layer, and Local sing-box separately installable and operable.
+
+Current behavior:
+- Existing runtime code is a Node HTTP server and Vite/React web UI for gateway and Mac-style client modes.
+- Earlier Windows docs describe adding Windows mode to that existing app.
+- The selected direction is now Tauri 2 + React/TypeScript + Rust as a separate Windows desktop app.
+
+Expected outcome:
+- `apps/windows-client` contains a Tauri 2 app.
+- The app has Overview, Profiles, Targets, Components, and Logs surfaces.
+- Profiles store process/folder/exe source items.
+- Targets store external proxy endpoints and optional local sing-box.
+- ProxiFyre is the first proxy router adapter.
+- Local sing-box is optional and never required for external target profiles.
+
+Target-perspective output:
+- User can install/run only the Control App.
+- User can see Proxyfier and Local sing-box as separate components.
+- User can add an external SOCKS5 target.
+- User can add a Discord process profile.
+- User can apply the profile to generated ProxiFyre config.
+- User sees activity confirming whether apply succeeded or why it was blocked.
+
+Truth owner:
+- Rust core domain crate owns normalized models and validation.
+- JSON source files under `C:\ProgramData\VpnProxy\config` own persisted profiles/targets/component preferences.
+- `ProxyRouterAdapter` owns conversion from source models to proxy-router generated config.
+- `SingBoxAdapter` owns generated local sing-box config and service contract.
+- React UI owns only transient UI state.
+
+Contract boundary:
+- UI -> Tauri commands with typed request/response DTOs.
+- Tauri commands -> Rust core services.
+- Core services -> adapter traits.
+- Adapter traits -> helper/install/service commands when privileged operations are needed.
+- Helper/install commands return structured JSON, never unstructured text for app logic.
+
+Cutover:
+- Add superseded notes to old Windows Node-mode docs.
+- Keep `docs/windows-client-product-tech-brief.md` as product brief.
+- Make this `PLAN.md` the execution plan.
+- Do not implement Windows by adding `APP_MODE=windows` to the current Node server.
+
+Displaced path:
+- Displace old "Windows mode in current web app" implementation.
+- Displace "full install vs ProxiFyre-only" as dominant architecture; those become recipes composed from separate components.
+
+Value density:
+- MVP must prove app-level routing with external proxy target and ProxiFyre before local sing-box work expands scope.
+
+Evidence gate:
+- Tests and build are not enough.
+- Capture app-visible state and generated config.
+- Capture Windows manual evidence for service/helper actions when those tasks execute.
+
+Acceptance evidence:
+- `cargo test` or equivalent Rust tests for domain/adapters.
+- frontend typecheck/test/build for React.
+- Tauri dev/build command result.
+- Screenshot or state dump showing Windows app surfaces.
+- Generated ProxiFyre config from a sample profile.
+- Manual Windows checklist when privileged components are present.
+
+Non-goals:
+- No Electron.
+- No extension of the current Node gateway/client UI for Windows MVP.
+- No global Windows system proxy changes.
+- No transparent routing without a proxy router.
+- No mandatory local sing-box.
+- No direct coupling of UI to ProxiFyre-specific config shape.
+
+Risk if wrong:
+- If built inside the current Node app, the product will inherit gateway/client assumptions and conflict with the selected Tauri direction.
+- If ProxiFyre is not behind an adapter, licensing or engine changes will force UI/data rewrites.
+- If privileged work is hidden behind apply, users lose control and failures become hard to diagnose.
+
+## Architecture Slice
+
+Files/directories to create:
+- `apps/windows-client/package.json`
+- `apps/windows-client/vite.config.ts`
+- `apps/windows-client/tsconfig.json`
+- `apps/windows-client/src/main.tsx`
+- `apps/windows-client/src/app/App.tsx`
+- `apps/windows-client/src/app/routes.tsx`
+- `apps/windows-client/src/api/tauriCommands.ts`
+- `apps/windows-client/src/domain/types.ts`
+- `apps/windows-client/src/features/overview/*`
+- `apps/windows-client/src/features/profiles/*`
+- `apps/windows-client/src/features/targets/*`
+- `apps/windows-client/src/features/components/*`
+- `apps/windows-client/src/features/logs/*`
+- `apps/windows-client/src/styles/*`
+- `apps/windows-client/src-tauri/Cargo.toml`
+- `apps/windows-client/src-tauri/tauri.conf.json`
+- `apps/windows-client/src-tauri/capabilities/default.json`
+- `apps/windows-client/src-tauri/src/main.rs`
+- `apps/windows-client/src-tauri/src/commands.rs`
+- `apps/windows-client/src-tauri/src/models.rs`
+- `apps/windows-client/src-tauri/src/storage.rs`
+- `apps/windows-client/src-tauri/src/activity.rs`
+- `apps/windows-client/src-tauri/src/adapters/proxy_router.rs`
+- `apps/windows-client/src-tauri/src/adapters/proxifyre.rs`
+- `apps/windows-client/src-tauri/src/adapters/singbox.rs`
+- `apps/windows-client/src-tauri/src/helper.rs`
+- `apps/windows-client/src-tauri/tests/*`
+- `apps/windows-client/scripts/install-control-app.ps1`
+- `apps/windows-client/scripts/install-proxyfier.ps1`
+- `apps/windows-client/scripts/install-singbox.ps1`
+
+Files to modify:
+- `README.md`
+- `docs/roadmap.md`
+- `docs/superpowers/specs/2026-05-21-windows-client-design.md`
+- `docs/superpowers/plans/2026-05-21-windows-client.md`
+- `docs/goals/windows-modular-client/GOAL.md`
+- `docs/goals/windows-modular-client/EVIDENCE.md`
+
+Files to avoid:
+- `src/server/*` except if a later explicit migration asks for shared code extraction.
+- `src/web/*` for Windows MVP.
+- Docker, entrypoint, and compose files.
+- macOS installer.
+
+Source of truth:
+- `C:\ProgramData\VpnProxy\config\profiles.json`
+- `C:\ProgramData\VpnProxy\config\targets.json`
+- `C:\ProgramData\VpnProxy\config\components.json`
+- `C:\ProgramData\VpnProxy\state\activity.json`
+
+Derived artifacts:
+- `C:\ProgramData\VpnProxy\generated\proxifyre-app-config.json`
+- `C:\ProgramData\VpnProxy\generated\sing-box-config.json`
+- ProxiFyre runtime config copied/backed up by helper/apply operation.
+
+Read path:
+- React UI calls Tauri commands.
+- Tauri commands read JSON source via Rust storage service.
+- Component status combines source preferences, filesystem checks, service checks, and helper responses.
+
+Write path:
+- React UI sends typed mutations.
+- Rust validates with domain models.
+- Rust writes source JSON atomically with backups.
+- Apply generates derived config and invokes adapter/helper.
+
+Integration points:
+- ProxiFyre adapter emits `app-config.json` compatible output.
+- Local sing-box adapter emits `sing-box` JSON config and validates via `sing-box check` when binary exists.
+- Tauri sidecar/helper permissions are declared explicitly.
+- Installer scripts may be launched or displayed explicitly, never silently during apply.
+
+Migration/cutover:
+- Older Windows docs point to this plan and source brief.
+- Existing Node app remains gateway/client only.
+- If shared subscription parsing is needed later, extract it intentionally into a shared package rather than importing server internals.
+
+Acceptance evidence gate:
+- MVP evidence must show external-target flow works without local sing-box.
+- Optional sing-box evidence must show the same profile model can switch targets after installing sing-box.
+
+## Task Board
+
+### Task 1: Supersede Old Windows Node Plan
+
+Owner: main agent
+
+Input:
+- `docs/windows-client-product-tech-brief.md`
+- old Windows docs/plans
+
+Files allowed:
+- `docs/superpowers/specs/2026-05-21-windows-client-design.md`
+- `docs/superpowers/plans/2026-05-21-windows-client.md`
+- `docs/roadmap.md`
+- `README.md`
+
+Files forbidden:
+- Runtime source files.
+
+Output:
+- Old Windows documents clearly point to this Tauri plan and no longer read as implementation authority.
+
+Evidence:
+- `rg -n "Tauri|superseded|windows-client-product-tech-brief|apps/windows-client" README.md docs`
+
+Depends on: none
+
+Parallel safe: yes
+
+### Task 2: Scaffold Tauri App Shell
+
+Owner: main agent
+
+Input:
+- Tauri 2 app structure
+- Product brief UI surfaces
+
+Files allowed:
+- `apps/windows-client/package.json`
+- `apps/windows-client/vite.config.ts`
+- `apps/windows-client/tsconfig.json`
+- `apps/windows-client/index.html`
+- `apps/windows-client/src/*`
+- `apps/windows-client/src-tauri/*`
+
+Files forbidden:
+- Current root `src/server/*`
+- Current root `src/web/*`
+
+Output:
+- Tauri app starts with empty shell and five navigation surfaces.
+- No business logic yet.
+
+Evidence:
+- `cd apps/windows-client && npm install && npm run build`
+- `cd apps/windows-client/src-tauri && cargo test` if Rust tests exist
+
+Depends on: Task 1
+
+Parallel safe: no
+
+### Task 3: Define Domain Models And Validation
+
+Owner: main agent
+
+Input:
+- Profile/Target/Component models from brief
+
+Files allowed:
+- `apps/windows-client/src-tauri/src/models.rs`
+- `apps/windows-client/src-tauri/src/validation.rs`
+- `apps/windows-client/src/domain/types.ts`
+- `apps/windows-client/src-tauri/tests/domain_tests.rs`
+
+Files forbidden:
+- Adapter/helper code except trait references.
+
+Output:
+- Typed Rust models for `Profile`, `ProfileItem`, `Target`, `ComponentStatus`, `ActivityEntry`.
+- TypeScript DTOs mirror Rust command responses.
+- Validation rejects malformed ports/protocols but allows missing local sing-box.
+
+Evidence:
+- Rust tests showing process/folder/exe normalization and external target validation.
+
+Depends on: Task 2
+
+Parallel safe: no
+
+### Task 4: Implement JSON Storage And Activity Log
+
+Owner: main agent
+
+Input:
+- Domain models from Task 3
+
+Files allowed:
+- `apps/windows-client/src-tauri/src/storage.rs`
+- `apps/windows-client/src-tauri/src/activity.rs`
+- `apps/windows-client/src-tauri/tests/storage_tests.rs`
+
+Files forbidden:
+- UI screens except command wiring stubs.
+
+Output:
+- Atomic JSON read/write for profiles, targets, components, and activity.
+- Backups before overwriting source files.
+- Config root defaults to `C:\ProgramData\VpnProxy`, with test override.
+
+Evidence:
+- Tests prove roundtrip, invalid JSON fallback behavior, backup creation, activity cap/sort.
+
+Depends on: Task 3
+
+Parallel safe: no
+
+### Task 5: Add Proxy Router Adapter Boundary And ProxiFyre Adapter
+
+Owner: main agent
+
+Input:
+- Domain models and storage
+
+Files allowed:
+- `apps/windows-client/src-tauri/src/adapters/proxy_router.rs`
+- `apps/windows-client/src-tauri/src/adapters/proxifyre.rs`
+- `apps/windows-client/src-tauri/tests/proxifyre_adapter_tests.rs`
+
+Files forbidden:
+- Direct UI coupling to ProxiFyre config fields.
+
+Output:
+- `ProxyRouterAdapter` trait.
+- `ProxiFyreAdapter` generates config from enabled profiles and targets.
+- External target flow does not require sing-box.
+
+Evidence:
+- Test generates ProxiFyre config for Discord + external SOCKS5 target.
+- Test blocks local-singbox target only when target requires missing component.
+
+Depends on: Task 4
+
+Parallel safe: no
+
+### Task 6: Add Tauri Commands
+
+Owner: main agent
+
+Input:
+- Storage and adapter services
+
+Files allowed:
+- `apps/windows-client/src-tauri/src/commands.rs`
+- `apps/windows-client/src-tauri/src/main.rs`
+- `apps/windows-client/src/api/tauriCommands.ts`
+- `apps/windows-client/src-tauri/tests/command_tests.rs`
+
+Files forbidden:
+- Full UI implementation beyond command call wrappers.
+
+Output:
+- Commands for status, profiles, targets, components, scan/resolve preview, apply, logs.
+- Commands return structured responses only.
+
+Evidence:
+- Command tests or integration tests prove apply generates derived config and records activity using a mock adapter/helper.
+
+Depends on: Task 5
+
+Parallel safe: no
+
+### Task 7: Build MVP UI
+
+Owner: main agent
+
+Input:
+- Tauri command API
+- Product brief layout
+
+Files allowed:
+- `apps/windows-client/src/app/*`
+- `apps/windows-client/src/features/overview/*`
+- `apps/windows-client/src/features/profiles/*`
+- `apps/windows-client/src/features/targets/*`
+- `apps/windows-client/src/features/components/*`
+- `apps/windows-client/src/features/logs/*`
+- `apps/windows-client/src/styles/*`
+
+Files forbidden:
+- Rust adapter behavior except fixing DTO mismatches.
+
+Output:
+- Compact utility UI with Overview, Profiles, Targets, Components, Logs.
+- User can create/edit profile, external target, and trigger apply.
+- Missing sing-box is shown as valid optional state.
+
+Evidence:
+- `npm run build`
+- Screenshot or browser/app state showing missing sing-box and usable external target flow.
+
+Depends on: Task 6
+
+Parallel safe: no
+
+### Task 8: Implement Helper And Explicit Installer Boundary
+
+Owner: main agent
+
+Input:
+- Component model
+- Security model from brief
+
+Files allowed:
+- `apps/windows-client/src-tauri/src/helper.rs`
+- `apps/windows-client/src-tauri/capabilities/default.json`
+- `apps/windows-client/scripts/install-control-app.ps1`
+- `apps/windows-client/scripts/install-proxyfier.ps1`
+- `apps/windows-client/scripts/install-singbox.ps1`
+- `apps/windows-client/src-tauri/tests/helper_tests.rs`
+
+Files forbidden:
+- Hidden installer invocation inside profile apply.
+
+Output:
+- Helper command abstraction for status/service/apply.
+- Installer scripts are explicit and idempotent.
+- Tauri sidecar/shell permissions are narrow and documented.
+
+Evidence:
+- Helper tests with mock command runner.
+- PowerShell parser checks for installer scripts.
+- Capability file shows limited sidecar permissions.
+
+Depends on: Task 6
+
+Parallel safe: partly, after command DTOs are stable
+
+### Task 9: Add Optional Local Sing-Box Adapter
+
+Owner: main agent
+
+Input:
+- sing-box target model
+- service/helper boundary
+
+Files allowed:
+- `apps/windows-client/src-tauri/src/adapters/singbox.rs`
+- `apps/windows-client/src-tauri/tests/singbox_adapter_tests.rs`
+- `apps/windows-client/src/features/components/*`
+- `apps/windows-client/src/features/targets/*`
+
+Files forbidden:
+- Making sing-box mandatory for external targets.
+
+Output:
+- Generate local sing-box config.
+- Validate via `sing-box check` when binary exists.
+- Local target appears only when installed/configured or as an explicit install prompt.
+
+Evidence:
+- Tests show external target apply works without sing-box.
+- Tests show local-singbox target requires installed/running component.
+
+Depends on: Tasks 5 and 8
+
+Parallel safe: no
+
+### Task 10: Package, Verify, And Record Evidence
+
+Owner: main agent
+
+Input:
+- Completed MVP implementation
+
+Files allowed:
+- `apps/windows-client/*`
+- `README.md`
+- `docs/roadmap.md`
+- `docs/goals/windows-modular-client/EVIDENCE.md`
+
+Files forbidden:
+- Unrelated app code.
+
+Output:
+- Build/test commands documented.
+- README explains separate Control App, Proxyfier, and Local sing-box install flows.
+- Evidence file captures automated and target-perspective proof.
+
+Evidence:
+- `npm run build`
+- Rust tests
+- Tauri build/dev proof
+- generated ProxiFyre config summary
+- UI screenshot/state
+- Windows manual checklist, or clearly mark `implemented but unproven` for Windows-only service behavior if not run on a Windows host.
+
+Depends on: all previous tasks
+
+Parallel safe: no
+
+## Manual Windows Verification Checklist
+
+1. Install/run only Control App.
+2. Verify Proxyfier and Local sing-box show missing as separate components.
+3. Add external SOCKS5 target.
+4. Add Discord process profile.
+5. Apply profile; verify generated ProxiFyre config and activity entry.
+6. Install Proxyfier separately; verify status changes.
+7. Apply profile to real Proxyfier service.
+8. Install Local sing-box separately.
+9. Import subscription or config, select outbound, and start Local sing-box.
+10. Switch existing profile from external target to Local sing-box and apply.
+11. Stop/restart Proxyfier and Local sing-box separately.
+12. Copy diagnostics and verify secrets are redacted.
+