zapret-kvn/docs/ai-handoff-singbox-editor-v1.md

AI Handoff: sing-box Raw Config Editor V1

Copy-Paste Prompt

Implement V1 of a raw sing-box.json editor in this repository.

Important: do exactly this scope and do not expand the product into a form builder, schema designer, or template system.

Product goal

Replace the current Маршруты page with a dedicated sing-box config editor page.

The user should edit a mostly final raw sing-box.json directly inside the app.

The app should almost not modify that config.

Critical product decisions

1. V1 is only for sing-box.
2. This is an engine-specific page. In the future other cores may get their own pages with their own architecture.
3. Delete the Маршруты page from the UI navigation for this task.
4. Do not build a template engine.
5. Do not build GUI fields for route rules, DNS, TLS, transports, or outbounds.
6. Do not use RoutingSettings to drive sing-box anymore.
7. The editor is the source of truth for sing-box config.
8. The user edits a fully formed JSON config.
9. The app may only do minimal runtime patching when necessary.
10. The only intended V1 runtime patch for usability is quick node switching: if the config contains an outbound with tag proxy, the app may replace that outbound with the currently selected Node converted to a sing-box outbound before launch.
11. If no outbound tag proxy exists, the app should launch the config as-is.
12. The config editor page is not tightly bound to the Серверы page, but selected nodes must still remain useful for quick switching as described above.
13. Маршруты must not affect sing-box at all after this change.
14. Do not call sing-box check in V1.
15. Validation in V1 should stay light:
    • read file
    • parse JSON
    • show JSON parse errors clearly
16. Keep the implementation simple and pragmatic.

Quick node switching rule

Use this exact convention:

• if the edited config contains an outbound object with "tag": "proxy", then right before launching sing-box, replace that outbound object with the currently selected node converted through the existing sing-box conversion path;
• preserve the tag as proxy;
• do not rewrite the rest of the config;
• do not merge RoutingSettings into the config;
• do not generate route rules from GUI state;
• if the selected node uses an unsupported transport for native sing-box conversion, fail with a clear user-visible error instead of silently falling back to the old routing builder.

Storage

Store sing-box editor files under:

• data/templates/sing-box/

For V1, one active config file is enough.

Persist in app state only what is needed to reopen that active config, such as:

• active config file name or relative path

UI requirements

Add a dedicated page for sing-box config editing with:

• large plain text editor for JSON
• open file / save file / save buttons
• new config button if useful
• validate button
• apply button or save-and-apply button
• optional pretty-format button if easy
• status/error area

Do not build advanced schema UI.

Behavior requirements

• The page edits raw JSON text.
• The page can load and save JSON files from the sing-box config folder.
• Validation only parses JSON and reports syntax errors with useful messages.
• Connecting in sing-box mode should use the saved editor config as the base config instead of building config from RoutingSettings.
• Before launch, optionally patch only the proxy outbound from the selected node as described above.
• Write the final runtime config to the existing runtime file path used by the app for sing-box launch.
• Keep existing node storage and node selection behavior.
• Keep app-managed behavior minimal.

Things you must not do

• do not create a placeholder/template DSL
• do not add route-rule form controls
• do not keep old Маршруты page visible
• do not silently combine editor JSON with RoutingSettings
• do not auto-generate a whole sing-box config from the selected node
• do not add heavy validation via external process execution
• do not rebuild or smoke-start the app automatically

Acceptance criteria

1. The Маршруты page is removed from navigation.
2. There is a dedicated sing-box editor page in the UI.
3. The page loads/saves raw JSON from data/templates/sing-box/.
4. JSON syntax errors are shown clearly.
5. In sing-box mode, the app launches from the editor config instead of the old routing builder.
6. If outbound tag proxy exists and a selected node is available, that one outbound is replaced from the selected node before launch.
7. If outbound tag proxy does not exist, the config is launched unchanged.
8. Маршруты no longer affect sing-box behavior.
9. Unsupported selected-node transports for proxy replacement produce a clear error instead of silent fallback.
10. The implementation remains simple and does not introduce a template system.

Files to read first

• xray_fluent/ui/main_window.py
• xray_fluent/ui/routing_page.py
• xray_fluent/application/controller.py
• xray_fluent/singbox_config_builder.py
• xray_fluent/singbox_manager.py
• xray_fluent/profiles/models.py
• xray_fluent/profiles/storage.py
• xray_fluent/constants.py
• docs/sing-box/runtime-config.md

Implementation strategy

1. Add storage path support for sing-box config files.
2. Add a small editor page widget for raw JSON editing.
3. Wire it into main navigation and remove the old routing page from visible UI.
4. Add controller methods to:
   • load active sing-box config text
   • save sing-box config text
   • parse/validate JSON
   • build final runtime config from editor JSON plus optional proxy outbound replacement
5. Change sing-box connect flow to use editor config as base config.
6. Keep the old builder code available only as internal helper for outbound conversion or fallback paths unrelated to this feature.
7. Do not do a large cleanup refactor unless required to make the feature work.

Output expectations

Make the code changes directly.

After implementation, report:

• what changed
• which files were added/modified
• how node-to-proxy replacement works
• what limitations remain in V1

Final Decisions

These decisions are already made and should not be re-opened:

• sing-box only in V1
• separate engine-specific page
• no route forms
• no template engine
• raw JSON editor
• Маршруты removed from UI
• Маршруты do not influence sing-box anymore
• minimal runtime patching only
• proxy outbound replacement from selected node is allowed
• no sing-box check in V1

Clarifying Notes

Why proxy replacement is allowed

The product still needs fast server switching using existing Node storage. The narrowest possible solution is to reserve tag proxy as the single replaceable outbound convention.

This keeps the editor raw and simple while preserving current node utility.

What "almost does not touch the config" means

It means:

• do not rebuild full config from app state
• do not merge route GUI state
• do not synthesize DNS/routing sections from forms
• only patch the selected-node outbound when the config opts into that by containing tag proxy

What to do with unsupported nodes

If selected node conversion cannot produce a native sing-box outbound, show a clear error and abort connect for that path. Do not silently switch to the old hybrid generator in this V1 unless that fallback is already trivial and fully compatible with the raw-config model.

Prefer explicit failure over hidden behavior.

Suggested Minimal UX

• page title: sing-box
• main editor area
• buttons:
  • Открыть
  • Сохранить
  • Проверить JSON
  • Применить
• small hint text:
  • config is raw sing-box.json
  • outbound tag proxy will be replaced by the selected server if present

Recommended Technical Shortcut

Do not over-model this in AppState.

For V1, it is enough to add a couple of fields to settings or state for:

• active sing-box config file path or name
• maybe unsaved editor text handling if you choose to persist it

Do not invent a large new profile schema.