chore: initialize proxyctl specification

2026-07-17 01:51:13 +08:00
commit c4a7616488
16 changed files with 553 additions and 0 deletions
@@ -0,0 +1,18 @@
+# 01 — Create and activate persistent Proxy Profiles
+
+**What to build:** A runnable `proxyctl` TUI in which a user can manage validated Proxy Profiles and select an Active Profile, establishing the first complete path from keyboard interaction through the Application Module to durable configuration.
+
+**Blocked by:** None — can start immediately.
+
+**Status:** ready-for-agent
+
+- [ ] Running `proxyctl` without arguments opens a keyboard-driven TUI and shows the Active Profile or a clear no-Profile state.
+- [ ] The Profile page lets the user create, view, edit, delete, and activate uniquely named Proxy Profiles.
+- [ ] Single proxy mode accepts one URL and expands it for compatible protocol uses without losing the user's value when advanced editing is opened.
+- [ ] Advanced mode supports distinct HTTP, HTTPS, and ALL/SOCKS URLs.
+- [ ] URL validation accepts only HTTP, HTTPS, SOCKS5, and SOCKS5H with valid hosts and ports and presents actionable validation errors.
+- [ ] Bypass validation accepts exact hostnames, domain suffixes, IPv4, IPv6, and CIDR, then normalizes and deduplicates entries.
+- [ ] No Profile is guessed or created automatically; the main page remains accessible when no Active Profile exists.
+- [ ] Profile configuration follows XDG conventions, is written atomically, and is restricted to the owning user.
+- [ ] Proxy passwords are obscured in rendered output and redacted from all errors produced by this slice.
+- [ ] Application-level tests drive Profile behavior through the Interface consumed by the TUI rather than private helpers.
@@ -0,0 +1,20 @@
+# 02 — Safely control the Shell Target
+
+**What to build:** The first complete Target Adapter, allowing Bash and Zsh users to enable or disable the Active Profile from the TUI and have the invoking parent Shell synchronize after exit, while establishing the reusable Target seam and safety model for later integrations.
+
+**Blocked by:** 01 — Create and activate persistent Proxy Profiles.
+
+**Status:** ready-for-agent
+
+- [ ] A shared Target Interface exposes description, inspection, and desired-state operations without leaking platform paths or commands to the TUI.
+- [ ] The Shell Target is Available only for detected Bash or Zsh environments; unsupported Shells are explained outside the main Target list.
+- [ ] Enabling writes the Active Profile as conventional upper- and lower-case HTTP, HTTPS, ALL, and bypass environment assignments.
+- [ ] Disabling emits the required unsets and restores any prior recognized Shell proxy state rather than silently discarding it.
+- [ ] Attempts to enable without an Active Profile fail immediately with a route to Profile management.
+- [ ] Inspection distinguishes Enabled, Disabled, External, and Drifted according to the glossary.
+- [ ] The TUI shows an applying state and changes the switch only after success; failures preserve or re-inspect the actual state and show a redacted explanation.
+- [ ] Shell integration install and uninstall operations are explicit, idempotent, and preserve unrelated user startup configuration.
+- [ ] After an integrated TUI invocation exits, the parent Bash or Zsh session loads the generated assignments or unsets.
+- [ ] Recovery metadata follows XDG state conventions, uses atomic writes and owner-only permissions where secrets may be present.
+- [ ] When invoked through `sudo`, Profile and user Target state resolve to the invoking user; a direct root login resolves to root.
+- [ ] A reusable Target contract harness verifies availability, all four states, enable, disable, restoration, idempotency, validation failure, permission failure, partial failure, and secret redaction without touching the host Shell configuration.
@@ -0,0 +1,18 @@
+# 03 — Control the APT Target
+
+**What to build:** An APT Target that persistently applies the Active Profile on Debian-family systems, preserves pre-existing APT proxy behavior, and reports real configuration and permission outcomes through the common Target experience.
+
+**Blocked by:** 02 — Safely control the Shell Target.
+
+**Status:** ready-for-agent
+
+- [ ] APT is Available only when the expected Debian-family tooling and configuration capability are detected.
+- [ ] The Target explanation states that APT supports proxy environment variables and that this integration provides persistent, privilege-boundary-safe configuration.
+- [ ] Enabling uses an isolated `proxyctl`-owned overlay wherever supported and does not rewrite unrelated APT configuration.
+- [ ] Disabling removes only the managed overlay and restores any previously effective recognized configuration.
+- [ ] Inspection reports Enabled when effective managed values match the Active Profile, External for recognized non-managed proxy settings, Drifted for mismatched managed settings, and Disabled otherwise.
+- [ ] Supported Profile protocol values and Bypass entries are translated without silently omitting data.
+- [ ] An incompatible protocol or Bypass entry prevents mutation and identifies the incompatible value.
+- [ ] Missing write authority produces immediate permission feedback and leaves or re-inspects the actual state.
+- [ ] Repeated enable and disable operations are idempotent.
+- [ ] Adapter contract and Target-specific tests use an isolated filesystem and fake APT command behavior; they never modify host package-manager configuration.
@@ -0,0 +1,18 @@
+# 04 — Control the Docker containers/builds Target
+
+**What to build:** A Docker client Target that applies the Active Profile as defaults for new containers and builds while preserving unrelated client configuration and clearly distinguishing this behavior from Docker daemon proxying.
+
+**Blocked by:** 02 — Safely control the Shell Target.
+
+**Status:** ready-for-agent
+
+- [ ] The Target is Available when the standard Docker client configuration model can be used for the owning user.
+- [ ] Its explanation states that it affects new containers and builds, not Docker daemon registry access or existing containers.
+- [ ] Enabling safely merges managed proxy defaults without removing unrelated Docker client settings.
+- [ ] Disabling restores recognized prior proxy defaults and retains all unrelated configuration.
+- [ ] Inspection distinguishes Enabled, Disabled, External, and Drifted, including externally edited managed values.
+- [ ] HTTP, HTTPS, ALL/SOCKS, and Bypass values are applied only where Docker's documented model can represent them.
+- [ ] Unsupported Profile data prevents mutation and is reported rather than silently discarded.
+- [ ] Secret-bearing configuration is owner-restricted and credentials are redacted from UI errors and logs.
+- [ ] Writes are atomic and repeated operations are idempotent.
+- [ ] Adapter contract and Target-specific tests use isolated Docker client configuration and never contact or modify a real Docker daemon.
@@ -0,0 +1,18 @@
+# 05 — Control the GNOME desktop proxy Target
+
+**What to build:** A GNOME desktop Target that applies the Active Profile through GNOME's official settings model, restores prior desktop proxy settings safely, and appears only when the required settings schema is available.
+
+**Blocked by:** 02 — Safely control the Shell Target.
+
+**Status:** ready-for-agent
+
+- [ ] The Target is Available only when the expected GNOME settings command and proxy schema are usable for the owning user.
+- [ ] The explanation states that it affects applications consuming GNOME system network settings and does not promise coverage of every graphical application.
+- [ ] Enabling records the recognized original proxy mode and values before applying the Active Profile.
+- [ ] Disabling restores the recorded original settings when managed values remain under `proxyctl` ownership.
+- [ ] Inspection distinguishes Enabled, Disabled, External, and Drifted using positive evidence from GNOME settings.
+- [ ] HTTP, HTTPS, SOCKS, and Bypass values are translated only when their semantics can be preserved.
+- [ ] Any unrepresentable protocol or Bypass rule rejects the operation before mutation with an actionable explanation.
+- [ ] Running through `sudo` operates on the invoking user's GNOME settings rather than root's desktop settings.
+- [ ] Command, session-bus, schema, and permission failures are reflected immediately without false success.
+- [ ] Adapter contract and Target-specific tests use a fake settings command and never modify the active desktop session.
@@ -0,0 +1,19 @@
+# 06 — Control the Docker daemon Target
+
+**What to build:** A systemd-managed Docker daemon Target that configures daemon network proxying separately from container defaults and performs an explicit, confirmed restart with truthful post-operation state.
+
+**Blocked by:** 02 — Safely control the Shell Target.
+
+**Status:** ready-for-agent
+
+- [ ] The Target is Available only when a supported systemd-managed Docker daemon is detected.
+- [ ] The explanation states that it affects daemon operations such as registry access, not container network traffic or container/build defaults.
+- [ ] Pressing Space presents a restart warning before any configuration mutation.
+- [ ] Cancelling the warning performs no file write, manager reload, or daemon restart.
+- [ ] Confirming applies the compatible Active Profile through a managed daemon configuration surface, reloads manager configuration as required, and immediately restarts Docker.
+- [ ] There is no Pending Restart state; success is reported only after restart and post-operation inspection succeed.
+- [ ] Failure to write, reload, or restart produces immediate redacted feedback and re-inspects actual configuration as Enabled, Disabled, External, or Drifted.
+- [ ] Existing recognized daemon proxy configuration is preserved and restored when the managed Target is disabled.
+- [ ] Unsupported protocol or Bypass data rejects the operation before mutation rather than being omitted.
+- [ ] Missing authority is reported as a normal permission error; the Adapter never initiates privilege escalation.
+- [ ] Adapter contract and Target-specific tests fake systemd and Docker behavior and prove cancellation, command ordering, restart failure, restoration, and idempotency without touching the host daemon.
@@ -0,0 +1,18 @@
+# 07 — Diagnose and reset managed Target state
+
+**What to build:** Operational maintenance behavior that lets users inspect configuration and permission problems, safely restore every managed Target before uninstalling, and troubleshoot failures from bounded redacted local logs.
+
+**Blocked by:** 02 — Safely control the Shell Target.
+
+**Status:** ready-for-agent
+
+- [ ] `proxyctl doctor` performs read-only checks of Profile validity, identity resolution, storage permissions, Target availability, detected state, required commands, and relevant write authority.
+- [ ] Diagnostic output states the evidence behind External or Drifted results and redacts all credentials.
+- [ ] `proxyctl reset` requires confirmation before changing any Target.
+- [ ] A confirmed reset attempts to disable every managed Target through the same Target Interface used by the TUI and restores recorded original state where safe.
+- [ ] Reset reports each Target result independently, preserves truthful state after partial failure, and exits unsuccessfully when any requested cleanup fails.
+- [ ] Cancellation performs no Target mutation.
+- [ ] Mutating operations are protected against concurrent `proxyctl` processes so recovery metadata cannot be corrupted.
+- [ ] Local logs record operation type, Target, result, and redacted failure detail without credentials or full authenticated URLs.
+- [ ] Log growth is bounded through rotation or equivalent retention behavior.
+- [ ] The maintenance commands have process-level tests using fake Targets and isolated XDG locations; tests never modify the host system.
@@ -0,0 +1,20 @@
+# 08 — Coordinate the Active Profile and complete the Target panel
+
+**What to build:** The complete everyday TUI experience across all first-release Targets, including dynamic discovery, contextual help, coordinated Active Profile changes, immediate per-Target progress, and safe handling of Profile deletion.
+
+**Blocked by:** 03 — Control the APT Target; 04 — Control the Docker containers/builds Target; 05 — Control the GNOME desktop proxy Target; 06 — Control the Docker daemon Target; 07 — Diagnose and reset managed Target state.
+
+**Status:** ready-for-agent
+
+- [ ] The main panel lists only Available Targets and refreshes availability and state on demand.
+- [ ] The help page lists every built-in Target, including hidden Targets and the reason each was not detected.
+- [ ] The selected Target's summary explains effects, non-effects, configuration ownership, expected permissions, and relevant side effects.
+- [ ] Arrow keys and `j`/`k` navigate, Space toggles, `p` opens Profile management, `r` refreshes, `?` opens help, and `q`/Escape returns or exits consistently.
+- [ ] The Active Profile is always visible on the main panel, including a clear absent state.
+- [ ] Attempting to enable any Target without an Active Profile fails immediately and points to Profile management; disabling remains possible.
+- [ ] Changing the Active Profile updates every Enabled Target one at a time and reflects progress and completion immediately on each row.
+- [ ] A cross-Target partial failure keeps successful updates, re-inspects failed Targets, marks Drifted where appropriate, and presents a redacted summary without attempting global rollback.
+- [ ] Deleting the final Proxy Profile requires confirmation, leaves existing managed configuration in place as Drifted, and prevents re-enabling until a new Active Profile exists.
+- [ ] External configuration can be temporarily overlaid by the Active Profile and is restored to External when the managed Target is disabled.
+- [ ] TUI tests cover key-to-intent mapping, page transitions, Active Profile rendering, all Target states, confirmation dialogs, progress, errors, and explanations without duplicating Application behavior tests.
+- [ ] Full Application integration tests exercise multiple fake and real hermetic Adapters through Active Profile switching and partial failure.
@@ -0,0 +1,18 @@
+# 09 — Publish a verifiable proxyctl v1
+
+**What to build:** A documented and reproducible first release that users on Linux amd64 and arm64 can install, verify, operate safely, diagnose, and remove without relying on distribution-specific packaging.
+
+**Blocked by:** 08 — Coordinate the Active Profile and complete the Target panel.
+
+**Status:** ready-for-agent
+
+- [ ] `proxyctl version` reports the build version in human-readable and script-friendly output.
+- [ ] Process-level smoke tests cover default TUI startup, version, doctor, reset confirmation, and Shell integration install/uninstall using an isolated environment.
+- [ ] The full automated suite proves no test modifies real Shell startup files, package-manager configuration, Docker state, GNOME settings, or system services.
+- [ ] Reproducible release automation builds single Linux binaries for amd64 and arm64.
+- [ ] Release automation emits SHA-256 checksums for every distributed binary or archive.
+- [ ] User documentation explains installation, first Profile creation, Shell integration, each Target's effects, all status meanings, permission behavior, explicit `sudo` use, Docker restart risk, diagnostics, reset, and uninstall cleanup.
+- [ ] Documentation states that `proxyctl` does not manage proxy processes, test connectivity, elevate privileges internally, collect telemetry, or check for updates automatically.
+- [ ] Documentation identifies the supported Linux, Shell, APT, Docker, and GNOME boundaries and the intentionally deferred integrations.
+- [ ] Source installation through Go tooling works without relying on deb, rpm, AUR, Snap, Flatpak, or another distribution package.
+- [ ] A clean-machine verification demonstrates installation, a Profile workflow, at least one hermetic Target workflow, diagnosis, reset, and removal.