ProxyWarden/.agent/skills/windows-services-powershell/SKILL.md

Skill: Windows Services / PowerShell / Elevation

Когда использовать

Используй этот skill при изменениях в scripts/*.ps1, ProxiFyre install/start/stop/uninstall, sing-box service control, UAC/admin checks, helper/elevation boundary, component detection.

Цель

Сохранять service/install operations явными, безопасными и проверяемыми. Пользователь должен понимать, что приложение собирается менять в системе. Компьютер пользователя — не песочница для творческих экспериментов агента, как ни печально.

Инварианты

• Install/start/stop/uninstall are explicit user actions.
• apply must not silently install/uninstall/start/stop components unless that behavior is clearly designed and surfaced.
• -PlanOnly scripts must be side-effect-free.
• PowerShell output intended for UI/backend must be structured JSON.
• Service detection must distinguish managed service from fuzzy candidate.
• Never relax safe-path checks to make uninstall easier.

Script rules

PowerShell scripts should:

• use Set-StrictMode -Version Latest where practical;
• set $ErrorActionPreference = 'Stop';
• return structured JSON for plan/status paths;
• avoid localized text parsing for control flow;
• avoid writing secrets to host output;
• have clear exit codes;
• support -PlanOnly for dry-run/status checks;
• avoid downloading/executing arbitrary remote scripts.

Elevation rules

When launching elevated PowerShell:

• keep command fixed and parameters escaped;
• avoid user-controlled script text;
• avoid predictable temp script names;
• do not pass secrets via command line;
• verify script path before launch;
• clean up temp artifacts best-effort;
• return clear error if user cancels UAC.

Service detection

Preferred approach:

1. Search known managed service names first.
2. Read service PathName through WMI/CIM.
3. Verify binary path and managed install metadata.
4. Only then mark as managed/controllable.
5. Fuzzy matches should be shown as candidates, not automatically controlled.

Testing

Pure logic can be tested cross-platform with mocks.

Real verification requires Windows:

& .\scripts\install-control-app.ps1 -PlanOnly
& .\scripts\install-proxyfier.ps1 -PlanOnly
& .\scripts\install-singbox.ps1 -PlanOnly
npm run tauri -- dev

For real service tests:

• Windows 10/11.
• Admin/UAC path.
• Fresh machine or VM snapshot.
• Existing ProxiFyre/sing-box absent.
• Existing fuzzy ProxiFyre-like service present, if testing safety.

Do not

• Do not claim actual service operations were tested unless they were run on Windows.
• Do not parse human-localized sc.exe output if structured WMI/CIM data is available.
• Do not delete paths from fuzzy discovery alone.
• Do not make scripts silently modify firewall/proxy/system settings outside their stated purpose.

Как отчитываться

Перед финальным ответом применить .agent/skills/communication-reporting/SKILL.md и .agent/checklists/communication.md.

Минимум для нетривиальной задачи:

• короткая сводка;
• таблица файлов Файл / Что изменилось / Зачем;
• важные места без пересказа каждой строки;
• что проверено;
• что не проверено;
• конкретные риски.