# Windows Local Sing-Box Implementation Plan

**Intent:** Add an optional Windows-client Local sing-box block that mirrors the ProxiFyre block, installs and controls a real sing-box service, imports a subscription/link, lets the user pick and ping servers, and routes selected apps through the chosen local outbound.
**Current Behavior:** The Windows client supports an existing external SOCKS5 proxy and a ProxiFyre component block with setup details, install/start/stop/uninstall actions, animation, and generated config apply. `singbox` exists as an optional component in the model, but `install-singbox.ps1` is only a marker boundary, `main.rs` does not register sing-box commands, the frontend has no sing-box block, and subscription parsing lives only in the Node server.
**Expected Outcome:** A Windows user can keep using the external proxy path unchanged, or explicitly install optional Local sing-box, paste a subscription/VLESS link, fetch servers, ping them, choose one, generate a checked sing-box config, start/stop the sing-box service, and apply ProxiFyre routing to `local-singbox`.
**Target-Perspective Output:** In the Windows client, the user sees a second optional block styled and animated like ProxiFyre. It shows what will be installed, asks for clear confirmation before privileged work, displays subscription/server state, exposes server ping and selection, and makes it obvious whether selected apps route to an existing proxy or to Local sing-box.
**Truth Owner:** Rust/Tauri backend owns sing-box source state, subscription parsing/cache, generated sing-box config, component detection, and service operations. React owns only transient UI state. Generated configs and service files are derived artifacts.
**Contract Boundary:** React calls typed Tauri commands. Rust validates and persists source JSON under `C:\ProgramData\VpnProxy`, generates configs through the sing-box adapter, and invokes explicit elevated PowerShell only for install/uninstall/service actions. UI never parses raw PowerShell/stdout.
**Cutover:** Replace the current marker-only sing-box installer path with a real optional Local sing-box component while preserving `ComponentId::Singbox` and `local-singbox` target semantics. Keep external proxy as the default usable route when sing-box is absent.
**Displaced Path:** Displace `apps/windows-client/scripts/install-singbox.ps1` marker behavior and the current direct-only `adapters/singbox.rs` output. Do not create a parallel Node/server subscription path for the Windows client.
**Value Density:** The smallest high-value slice is a controlled Local sing-box block that can fetch a subscription, select an outbound, generate checked local sing-box config, and expose service controls without making sing-box mandatory.
**Evidence Gate:** Evidence must include target-perspective UI proof plus generated config proof, not just tests. Privileged Windows service behavior must be manually verified or explicitly marked `implemented but unproven`.
**Acceptance Evidence:** Rust tests for parser/config/service-command boundaries; frontend build; app state or screenshot showing ProxiFyre and Local sing-box blocks; generated `sing-box-config.json` containing the selected outbound and local mixed inbound; generated ProxiFyre config pointing to `127.0.0.1:1080`; Windows service checklist when elevated actions are run.
**Evidence Lane:** Record commands, selected app state, generated config summaries, and manual Windows results in `docs/goals/windows-local-singbox/EVIDENCE.md`.
**Kill Criteria:** No mandatory sing-box for external proxy flow; no hidden install during profile apply; no duplicate subscription source of truth in React or Node server; no raw PowerShell text as app logic; no permanent marker-only sing-box install path.
**Architecture Slice:** Extend `apps/windows-client` only: Rust domain/storage/commands/adapters/detection/scripts plus React UI/types/CSS. Avoid root `src/server` and root `src/web` except as read-only reference.
**Plan Review Gate:** Requires PRE review before execution.

## Terminology

The user-facing feature name is `Local sing-box` / `sing-box`. Do not use alternate feature names in UI, commands, docs, or files.

## Architecture Slice

Files to create:
- `apps/windows-client/src-tauri/src/subscription.rs`
- `apps/windows-client/src-tauri/src/singbox_service.rs`
- `apps/windows-client/src-tauri/tests/subscription_tests.rs`
- `apps/windows-client/src-tauri/tests/singbox_service_tests.rs`
- `apps/windows-client/src-tauri/tests/singbox_command_tests.rs`

Files to modify:
- `apps/windows-client/src-tauri/Cargo.toml`
- `apps/windows-client/src-tauri/src/main.rs`
- `apps/windows-client/src-tauri/src/models.rs`
- `apps/windows-client/src-tauri/src/storage.rs`
- `apps/windows-client/src-tauri/src/commands.rs`
- `apps/windows-client/src-tauri/src/component_detection.rs`
- `apps/windows-client/src-tauri/src/adapters/singbox.rs`
- `apps/windows-client/src-tauri/tests/singbox_adapter_tests.rs`
- `apps/windows-client/src-tauri/tests/command_tests.rs`
- `apps/windows-client/src/domain/types.ts`
- `apps/windows-client/src/api/tauriCommands.ts`
- `apps/windows-client/src/app/App.tsx`
- `apps/windows-client/src/styles/app.css`
- `apps/windows-client/scripts/install-singbox.ps1`
- `apps/windows-client/README.md`
- `docs/goals/windows-local-singbox/EVIDENCE.md`

Files to avoid:
- `src/server/*` except as read-only reference for subscription semantics.
- `src/web/*`
- Docker, compose, gateway, and macOS installer files.
- Existing ProxiFyre behavior except where it must consume the `local-singbox` target.

Source of truth:
- `C:\ProgramData\VpnProxy\config\profiles.json`
- `C:\ProgramData\VpnProxy\config\targets.json`
- `C:\ProgramData\VpnProxy\config\local-singbox.json`
- `C:\ProgramData\VpnProxy\state\singbox-subscription-cache.json`
- `C:\ProgramData\VpnProxy\state\activity.json`

Derived artifacts:
- `C:\ProgramData\VpnProxy\generated\sing-box-config.json`
- `C:\ProgramData\VpnProxy\generated\proxifyre-app-config.json`
- Installed `sing-box.exe` and WinSW wrapper under `C:\Program Files\VpnProxy\sing-box`
- Windows service `VpnProxySingBox`

Read path:
- React calls `get_components`, `get_singbox_status`, `get_singbox_setup_status`, and subscription/server commands.
- Rust reads source Local sing-box config and cache, detects installed `sing-box`/service/wrapper, and returns redacted DTOs.

Write path:
- React sends typed mutations for subscription URL, selected server, local endpoint, and service actions.
- Rust validates input, writes source JSON atomically, fetches/cache subscription data, generates `sing-box-config.json`, and runs `sing-box check` before service start/restart.

Contract boundary:
- `subscription.rs` owns fetch/parse/link normalization.
- `adapters/singbox.rs` owns conversion from selected outbound to local runtime config.
- `singbox_service.rs` owns install/service script generation and structured command parsing.
- `commands.rs` owns Tauri DTOs and activity entries.
- `App.tsx` owns layout/state orchestration only.

Integration points:
- ProxiFyre route remains `selected apps -> ProxiFyre -> target`.
- Local sing-box route uses target `local-singbox`, `kind=local`, `protocol=socks5`, `host=127.0.0.1`, `port=1080`, `requiresComponent=singbox`.
- Server ping uses TCP connect to the selected outbound host/port, like the existing server ping semantics.
- Install flow downloads/installs `sing-box` plus a WinSW Windows service wrapper, then writes machine-readable result JSON.

Migration/cutover:
- On first sing-box save/start, ensure `local-singbox` target exists or is updated from Local sing-box listen settings.
- Do not switch the user's profile target automatically unless the user chooses Local sing-box.
- Existing external proxy input remains the default path and must still build/apply without sing-box.

Displaced path:
- `install-singbox.ps1` must stop being a marker-only script.
- The old direct-only sing-box config in `adapters/singbox.rs` must be replaced by selected-subscription-outbound config generation.
- No Windows-client code should import or call the root Node server for subscription parsing.

Acceptance evidence gate:
- Automated evidence proves parser/config/ping/service-command boundaries.
- App-visible evidence proves the optional block, setup details, server selection, and route mode.
- Generated config evidence proves selected server is used by sing-box and ProxiFyre points to the local endpoint.

## Task Board

### Task 1: Add Local Sing-Box Domain And Storage Contract

Allowed files:
- `apps/windows-client/src-tauri/src/models.rs`
- `apps/windows-client/src-tauri/src/storage.rs`
- `apps/windows-client/src/domain/types.ts`
- `apps/windows-client/src-tauri/tests/storage_tests.rs`

Expected output:
- `LocalSingBoxConfig` source model with subscription URL, redacted display URL, selected server tag, listen host/port, service name, install root, and timestamps.
- `SubscriptionCache` model with parsed config, server summaries, user info, and fetched timestamp.
- Storage paths for `config/local-singbox.json` and `state/singbox-subscription-cache.json`.

Verification:
- `cd apps/windows-client/src-tauri && cargo test storage`

Acceptance evidence:
- Tests prove atomic roundtrip, default optional empty state, redacted URL DTO, and invalid cache fallback.

Parallel safe: no.

### Task 2: Port Subscription Parsing And Fetching To Rust

Allowed files:
- `apps/windows-client/src-tauri/Cargo.toml`
- `apps/windows-client/src-tauri/src/subscription.rs`
- `apps/windows-client/src-tauri/tests/subscription_tests.rs`

Expected output:
- Parser supports sing-box JSON configs, base64 subscription bodies, and VLESS REALITY links with the same supported outbound types as `src/server/subscription.js`.
- Fetch command support is implemented in Rust with HTTP/HTTPS only and structured errors.
- Subscription URL is never echoed unredacted in diagnostics or normal status DTOs.

Verification:
- `cd apps/windows-client/src-tauri && cargo test subscription`

Acceptance evidence:
- Tests cover JSON config, base64 VLESS list, invalid URL, unsupported outbound, and redaction.

Parallel safe: yes after Task 1 model names are stable.

### Task 3: Replace Sing-Box Adapter With Selected-Outbound Config Generation

Allowed files:
- `apps/windows-client/src-tauri/src/adapters/singbox.rs`
- `apps/windows-client/src-tauri/tests/singbox_adapter_tests.rs`

Expected output:
- Adapter builds local mixed inbound on the configured listen host/port.
- Adapter selects the cached outbound by tag, clones it, ensures a stable outbound tag, and adds `direct`/`block`.
- Adapter runs `sing-box check` when a binary path is available.

Verification:
- `cd apps/windows-client/src-tauri && cargo test singbox_adapter`

Acceptance evidence:
- Tests show selected VLESS outbound appears in generated config, missing selected tag blocks generation, and external-target ProxiFyre flow remains independent from Local sing-box.

Parallel safe: yes after Task 1.

### Task 4: Implement Sing-Box Detection, Setup Status, And Service Scripts

Allowed files:
- `apps/windows-client/src-tauri/src/component_detection.rs`
- `apps/windows-client/src-tauri/src/singbox_service.rs`
- `apps/windows-client/scripts/install-singbox.ps1`
- `apps/windows-client/src-tauri/tests/component_detection_tests.rs`
- `apps/windows-client/src-tauri/tests/singbox_service_tests.rs`

Expected output:
- Detection finds installed `sing-box.exe`, service `VpnProxySingBox`, service running state, version/path, and problems.
- Setup status lists exactly what will be installed: sing-box binary, WinSW service wrapper, service name, install root, generated config/log paths.
- Install script performs a real idempotent install/repair boundary using WinSW and returns structured JSON; uninstall is safe-scoped to the configured install root.

Verification:
- `cd apps/windows-client/src-tauri && cargo test component_detection singbox_service`
- Windows parser check for `install-singbox.ps1` when running on Windows.

Acceptance evidence:
- Tests prove missing/installed/running component merge and PowerShell result parsing. Manual service install/start evidence is recorded later.

Parallel safe: yes, but integrate with Task 6 before UI.

### Task 5: Add Tauri Sing-Box Commands

Allowed files:
- `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`
- `apps/windows-client/src-tauri/tests/singbox_command_tests.rs`

Expected output:
- Commands: `get_singbox_status`, `get_singbox_setup_status`, `save_singbox_subscription`, `fetch_singbox_subscription`, `forget_singbox_subscription`, `select_singbox_server`, `ping_singbox_server`, `ping_all_singbox_servers`, `generate_singbox_config`, `start_singbox_service`, `stop_singbox_service`, `install_singbox`, `uninstall_singbox`.
- Commands update activity with structured entries.
- `generate_singbox_config` ensures/updates the `local-singbox` target but does not change profile targets without user choice.
- `start_singbox_service` regenerates and checks config from current source state before starting the service.

Verification:
- `cd apps/windows-client/src-tauri && cargo test command singbox_command`

Acceptance evidence:
- Tests prove fetch/cache/select/generate flow and ProxiFyre apply blocks only when a profile actually targets missing/stopped Local sing-box.

Parallel safe: no; depends on Tasks 1-4.

### Task 6: Build The Optional Local Sing-Box UI Block

Allowed files:
- `apps/windows-client/src/app/App.tsx`
- `apps/windows-client/src/domain/types.ts`
- `apps/windows-client/src/api/tauriCommands.ts`
- `apps/windows-client/src/styles/app.css`

Expected output:
- A second block appears beside/under ProxiFyre, visually matching `finder-card`, setup details, action menu, status light, and border animation behavior.
- UI shows Local sing-box as optional, not an error, when missing.
- User can paste subscription/link, fetch servers, select server, ping one/all, generate config, install/start/stop/uninstall Local sing-box, and choose whether the main profile uses existing proxy or Local sing-box.
- Loading/error/success states are visible and controlled by user action.

Verification:
- `cd apps/windows-client && npm run build`

Acceptance evidence:
- Screenshot or app state shows ProxiFyre block and Local sing-box block, expanded setup details, fetched server list with ping state, and route target toggle.

Parallel safe: no; depends on Task 5 DTOs.

### Task 7: Integrate Route Choice And ProxiFyre Apply

Allowed files:
- `apps/windows-client/src/app/App.tsx`
- `apps/windows-client/src-tauri/src/commands.rs`
- `apps/windows-client/src-tauri/src/adapters/proxifyre.rs`
- `apps/windows-client/src-tauri/tests/command_tests.rs`
- `apps/windows-client/src-tauri/tests/proxifyre_adapter_tests.rs`

Expected output:
- Main profile can target either external proxy or `local-singbox`.
- Switching to Local sing-box writes `targetId=local-singbox`; switching back writes external target.
- ProxiFyre generated config points to `127.0.0.1:1080` when Local sing-box is selected and still points to the entered external proxy otherwise.

Verification:
- `cd apps/windows-client/src-tauri && cargo test proxifyre_adapter command`
- `cd apps/windows-client && npm run build`

Acceptance evidence:
- Generated ProxiFyre config samples for both external proxy and Local sing-box routes are recorded.

Parallel safe: no.

### Task 8: Documentation, Evidence, And Windows Manual Gate

Allowed files:
- `apps/windows-client/README.md`
- `docs/goals/windows-local-singbox/EVIDENCE.md`
- `docs/goals/windows-modular-client/EVIDENCE.md`

Expected output:
- README explains separate ProxiFyre and Local sing-box install flows, data paths, service name, and rollback.
- Evidence file records tests/builds/UI proof/generated configs/manual Windows service checks.
- If elevated service install cannot be run in the current environment, record `implemented but unproven` for that lane with exact remaining manual steps.

Verification:
- `git status --short`
- Evidence commands listed in `EVIDENCE.md`.

Acceptance evidence:
- A target-perspective checklist proves the external proxy path still works and Local sing-box path works or is explicitly unproven only at the privileged Windows service lane.

Parallel safe: no.

## PRE Review Prompt

Use `C:\Users\PC\.agents\skills\krypton-planning\plan-reviewer-prompt.md` with:

- Plan file: `docs/goals/windows-local-singbox/PLAN.md`
- Original request: add an optional Windows-client Local sing-box block like ProxiFyre, with install/service management, connection link/subscription import, server selection, ping, animations, and user-controlled visibility of what will be installed.
- Unsafe paths or layers: root `src/server`, root `src/web`, hidden installer calls inside apply, raw PowerShell parsing in React, duplicate subscription state.
