From 1cc4c4c3d5d231c3e340530f348acc19c13289e4 Mon Sep 17 00:00:00 2001 From: Ixniy Evonniy Date: Wed, 1 Jul 2026 11:20:07 +0300 Subject: [PATCH] clean: remove unnecessary files, update AGENTS.md --- .gitignore | 5 ++-- AGENTS.md | 14 +++++++++++ singbox_tray_plan.md | 58 -------------------------------------------- 3 files changed, 16 insertions(+), 61 deletions(-) delete mode 100644 singbox_tray_plan.md diff --git a/.gitignore b/.gitignore index 54cfffb..86adb1d 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,4 @@ -# Jai compiler output +# Jai compiler output *.exe *.pdb *.lib @@ -6,8 +6,7 @@ .build/ # Local configurations & logs -config.json -config_run.json +config*.json *.log # Third-party binaries diff --git a/AGENTS.md b/AGENTS.md index 04d265c..d3f9496 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,3 +1,16 @@ +# Project-Specific Agent Guidelines: jai-sing-box + +This project implements a lightweight Windows system tray controller for `sing-box` (a universal proxy platform) written in the **Jai** programming language. + +**Key Project Notes**: +- The built executable is `singbox_tray.exe`. +- sing-box core is downloaded on-demand and installed to `%LOCALAPPDATA%\singbox-tray\`. +- **CRITICAL**: Never terminate sing-box or singbox_tray processes (see section 5). +- Uses only native Win32 APIs (WinINet, no libcurl dependency). +- Build via `build.jai` metaprogram (sets windows subsystem, custom entry). + +--- + # Jai Developer Agent Guidelines These guidelines apply to any agent working with the Jai programming language. @@ -40,4 +53,5 @@ These guidelines apply to any agent working with the Jai programming language. ## 5. Process Management Warning (VPN Connectivity) - **CRITICAL WARNING**: Do NOT kill, terminate, or stop the `sing-box` or `singbox_tray` processes during runtime unless explicitly instructed by the user. The agent's own network connection and container/sandbox internet access might be routed through this active VPN. Killing it will sever the agent's connection. +- **Rebuilding & Locked Executables**: Always try to compile the project first. Do not preemptively ask the user to close the executable unless compilation actually fails with a file lock error (e.g. `LNK1104` or similar) and you have verified that the locked file is indeed the output binary in the build directory. Only ask the user to close/free the executable in that specific failure case. diff --git a/singbox_tray_plan.md b/singbox_tray_plan.md deleted file mode 100644 index 49b8f7f..0000000 --- a/singbox_tray_plan.md +++ /dev/null @@ -1,58 +0,0 @@ -# Planning: Sing-box Windows Tray Controller in Jai - -We will implement a lightweight, headless Windows tray application in the **Jai** language to control the `sing-box` core. - -## 1. Core Architecture - -The application will run with a hidden/message-only window to remain headless, handling tray interaction, background updates, and process management. - -```mermaid -graph TD - A[Main Loop / Hidden Window] --> B[System Tray Icon] - B -->|Right Click| C[Context Menu] - C -->|Set URL| D[Custom Edit Dialog] - C -->|Start/Stop| E[Process Manager: sing-box.exe] - C -->|Update Now| F[Auto-Update Loop: WinINet] - C -->|Exit| G[Shutdown & Cleanup] - F -->|Timer/Thread| F -``` - -## 2. Component Design - -### A. Headless Window & System Tray Icon -- **Win32 Window**: We register a window class and create a hidden utility window using `CreateWindowExW`. This window serves as the message receiver. -- **Tray Icon**: We register a system tray icon via `Shell_NotifyIconW` (using `NOTIFYICONDATAW`). -- **Events**: We define a custom window message `WM_TRAY_CALLBACK` (`WM_USER + 1`). When the tray icon receives input (e.g. mouse clicks), Windows sends `WM_TRAY_CALLBACK` to our hidden window. -- **Context Menu**: On `WM_RBUTTONUP` (right click) or `WM_LBUTTONUP` (left click) over the tray icon, we load a dynamic popup menu using `CreatePopupMenu`, `AppendMenuW`, and `TrackPopupMenu`. - -### B. Custom Modal Dialog (Set URL) -To avoid needing an external resource compiler (`.rc`) or complex UI libraries, we will implement a clean, lightweight modal window: -- **Dialog Window**: A popup window using `WS_POPUP | WS_CAPTION | WS_SYSMENU` centered on screen. -- **Controls**: - - A static label: "Enter Sing-box Config URL:" - - An edit control (`EDIT` window class) to input the URL. - - An OK button and a Cancel button (`BUTTON` window class). -- **Behavior**: Block interactions with other menus, read the edit text on OK, write it to a `url.txt` file, and trigger an immediate config update. - -### C. Config Downloader (Auto-Update Engine) -- **Downloader**: Use the Windows WinINet API to perform HTTP/HTTPS requests. -- **Storage**: Save the downloaded JSON content to `config.json` in the same directory as the executable. -- **Auto-Update Thread**: Spawn a background thread (using `Thread` module) that sleeps for a set interval (e.g., 1 hour), then downloads the URL. If the file content changes, it updates `config.json` and restarts the `sing-box` process if it was running. - -### D. Process Management (`sing-box.exe`) -- **Process Spawning**: Use the standard `Process` module's `create_process` to run: - `sing-box.exe run -c config.json` -- **Job Object**: Windows processes started via `create_process` will be assigned to a Job Object with `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE`. This ensures `sing-box.exe` automatically shuts down when the controller application is closed. -- **Status Checking**: Use `get_process_result` with 0 timeout to check if sing-box is actively running. - -## 3. Implementation Steps - -1. **`main.jai`**: Core application entry point, hidden window loop, tray icon management. -2. **`dialog.jai`**: Edit-box dialog for config URL input. -3. **`updater.jai`**: WinINet HTTP/HTTPS client and background auto-update thread. -4. **`build.jai`**: Jai build script (metaprogram) to compile the app without standard console window popup (using `-subsystem windows`). - -## 4. Key Questions & Decisions - -- **Tray Icon**: Do we need a default/builtin icon? Yes, we will use a standard Windows system icon (like `IDI_APPLICATION` or `IDI_SHIELD`) so that the application works out-of-the-box without requiring an external `.ico` asset. -- **sing-box Location**: We will assume `sing-box.exe` is in the same directory as the controller. If not found there, we will search the system PATH.