harbor-net/docs/goals/windows-local-singbox/PLAN.md

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.