diff --git a/Furious/Backends/AGENTS.md b/Furious/Backends/AGENTS.md index f2f0258..c559d92 100644 --- a/Furious/Backends/AGENTS.md +++ b/Furious/Backends/AGENTS.md @@ -8,6 +8,18 @@ - Preserve full user-authored core documents and unknown supported fields. Report a lossless-compatibility failure instead of silently compiling or deleting unsupported configuration. +## Structured editor contract + +- `factoryToInput()` is normally observational: loading an editor must not add defaults or otherwise mutate the + configuration document unless that backend has a documented compatibility normalization, such as Xray transport + aliases. +- `inputToFactory()` writes only fields represented by the editor and returns whether it actually changed the + document. Do not materialize an absent effective default merely because the editor displays it. +- Display unknown future string values exactly and preserve them on an untouched load/save round trip. Editing one + known leaf must preserve unknown fields and unknown siblings elsewhere in the same object. +- A deliberate user switch to a supported tagged variant may replace the incompatible active variant. Keep unrelated + extension fields, and do not treat a fallback page used for display as a user selection. + ## Native TUN policy For a normal connection: diff --git a/Furious/Backends/ExternalCore/AGENTS.md b/Furious/Backends/ExternalCore/AGENTS.md new file mode 100644 index 0000000..bcd388e --- /dev/null +++ b/Furious/Backends/ExternalCore/AGENTS.md @@ -0,0 +1,25 @@ +# External Core backend guidance + +## Configuration contract + +- External Core is protocol-agnostic. Keep executable path, working directory, argument vector, environment mapping, + proxy endpoints, shutdown timeout, and application-tun2socks choice as distinct fields. +- The editor projects these known fields but must preserve unknown top-level fields. Loading is observational and an + untouched save must not normalize paths, arguments, environment variables, or future fields. +- Execute with `shell=False`. Never concatenate arguments into a shell command or log credentials/environment secrets. + +## Runtime and TUN ownership + +- Own the exact `Popen` instance and its reader/watcher resources. Startup failure and shutdown must close callbacks, + terminate, kill if necessary, and reap the exact child within configured bounds. +- Application tun2socks is explicit and requires a valid remote address. This backend does not inject a native core TUN + block or infer protocol-specific behavior. +- Validation dialogs are transient asynchronous UI: use the established `open()` ownership path and release them on + destruction without retaining them in backend or plugin registries. + +## Code review and verification + +- Flag shell execution, ambiguous string arguments, inherited transient callbacks, unknown-field loss, and unbounded + child-process cleanup. +- Use fully mocked subprocess and host-network operations. Test mapping round trips, unknown-field preservation, + validation failures, output-reader shutdown, tun2socks validation, and repeated editor/dialog destruction. diff --git a/Furious/Backends/Hysteria1/AGENTS.md b/Furious/Backends/Hysteria1/AGENTS.md new file mode 100644 index 0000000..64762dd --- /dev/null +++ b/Furious/Backends/Hysteria1/AGENTS.md @@ -0,0 +1,22 @@ +# Hysteria1 backend guidance + +## Compatibility boundary + +- Hysteria1 is an independent legacy backend with its own flat client schema and `hysteria://` share-link behavior. + Do not import Hysteria2 nested configuration, obfuscation, or native-TUN assumptions into it. +- Its structured editor follows the shared observational-load/minimal-write contract. Unknown future string values in + combo-backed fields remain visible and survive an untouched round trip. +- Preserve existing tolerant handling of malformed legacy field types unless a deliberate compatibility migration is + part of the task; do not silently rewrite valid user values while loading. + +## Runtime and assets + +- Runtime setup owns Hysteria1-specific MMDB, geosite, and rule assets. Keep asset preparation and failure cleanup in + this backend rather than shared connection managers. +- Proxy-only tests operate on a copy, set their temporary proxy listener, and must not alter the stored profile. + +## Code review and verification + +- Flag accidental reuse of Hysteria2 keys, loss of unknown flat fields, or editor factories retained as live widgets. +- Test URI and mapping compatibility, unknown combo values, runtime document immutability, asset failures, process + cleanup, and transient editor destruction. diff --git a/Furious/Backends/Hysteria2/AGENTS.md b/Furious/Backends/Hysteria2/AGENTS.md new file mode 100644 index 0000000..3646725 --- /dev/null +++ b/Furious/Backends/Hysteria2/AGENTS.md @@ -0,0 +1,29 @@ +# Hysteria2 backend guidance + +## Native document and structured editor + +- The persisted Hysteria2 client document is the configuration submitted to the embedded core. The compact editor is + a partial projection, not a compiler or schema normalizer. +- Keep upstream field names and values exact. In particular, `realm.ipMode` uses the native values `dual`, `v4`, and + `v6`; an absent value has the effective dual-stack default. Unknown future strings remain visible and untouched. +- Optional nested controls edit only their leaf. Preserve unknown siblings, and do not create optional groups or + effective Gecko packet defaults until the user actually changes the represented value. +- `obfs.type` selects a tagged subtype object. An unknown type must remain visible and preserve its subtype on an + untouched round trip. An explicit user switch to a known type may remove the previously active incompatible subtype, + while retaining unrelated extension data. + +## Runtime, statistics, and TUN + +- Runtime materialization passes a derived full Hysteria2 document to `startFromJSON`; do not translate it through an + Xray-shaped intermediate representation. +- With native TUN enabled, replace the runtime `tun` block with the generated block. With it disabled, preserve and + recognize a user `tun` block. Download/probe configurations explicitly omit TUN. +- Keep management/statistics requests bounded and separate from GUI objects. Runtime and worker ownership follows the + parent backend and Qt lifetime guidance. + +## Code review and verification + +- Flag `_modified` shadow state, dynamic combo-item accumulation, fallback pages mistaken for user selections, and + nested writes that replace an entire user object. +- Test known and unknown values, nested sibling preservation, obfs subtype switching, absent-default preservation, + native-TUN matrices, proxy-only stripping, and editor destruction. diff --git a/Furious/Backends/Xray/AGENTS.md b/Furious/Backends/Xray/AGENTS.md new file mode 100644 index 0000000..f625698 --- /dev/null +++ b/Furious/Backends/Xray/AGENTS.md @@ -0,0 +1,27 @@ +# Xray backend guidance + +## Documents and editors + +- The full Xray JSON document is authoritative. Structured editors project only the selected `proxy` outbound, + transport, and TLS fields; preserve every unrelated inbound, outbound, routing field, and extension. +- Transport and security loading preserves unknown `network` or `security` strings so they remain visible and survive + an untouched round trip. +- `http`, `gun`, and `mkcp` are legacy transport aliases that the editor intentionally normalizes to `h2`, `grpc`, and + `kcp` while loading. Keep this compatibility rewrite explicit and covered by tests. +- Selecting a different known transport or security mode may replace incompatible represented settings. Preserve + unknown sibling settings that the selected editor does not own. + +## Runtime, routing, and TUN + +- Prepare routing, logging, tests, and native TUN only on runtime copies. Keep the selected profile document intact. +- With Xray native TUN enabled, replace runtime TUN inbounds with the generated inbound. With it disabled, preserve and + recognize user TUN inbounds. Proxy-only tests explicitly strip TUN. +- Xray API statistics, routing assets, and transient asset/routing windows belong to this backend. Keep window owners + explicit and never register live editor or dialog instances globally. + +## Code review and verification + +- Flag editor loading that mutates configuration outside the documented transport-alias normalization or materializes + unrelated defaults. +- Test URI/mapping round trips, unknown transport/security preservation, routing and TUN runtime-copy behavior, asset + failure cleanup, and transient editor/window destruction.