From 61e88a628158062fcf4651ad9b0b8235701865c6 Mon Sep 17 00:00:00 2001 From: proxyctl coordinator Date: Sun, 30 Aug 2026 10:00:23 +0800 Subject: [PATCH] chore: move issue tracking to Gitea --- .../issues/01-persistent-proxy-profiles.md | 18 ----------- .scratch/proxyctl/issues/02-shell-target.md | 20 ------------- .scratch/proxyctl/issues/03-apt-target.md | 18 ----------- .../issues/04-docker-containers-target.md | 18 ----------- .scratch/proxyctl/issues/05-gnome-target.md | 18 ----------- .../issues/06-docker-daemon-target.md | 19 ------------ .../issues/07-diagnostics-and-reset.md | 18 ----------- .../issues/08-coordinate-target-panel.md | 20 ------------- .scratch/proxyctl/issues/09-release-v1.md | 18 ----------- .../issues/01-responsive-tui-foundation.md | 19 ------------ .../issues/02-operations-console-dashboard.md | 20 ------------- .../03-progressive-startup-and-refresh.md | 23 -------------- .../04-operation-coordination-and-status.md | 21 ------------- .../issues/05-contextual-target-actions.md | 24 --------------- .../issues/06-active-profile-picker.md | 19 ------------ .../issues/07-profile-management-page.md | 19 ------------ .../tui-redesign/issues/08-profile-editor.md | 19 ------------ .../issues/09-protocol-probe-field-action.md | 19 ------------ .../issues/10-help-dialog-and-navigation.md | 19 ------------ ...-accessibility-privacy-render-hardening.md | 24 --------------- AGENTS.md | 4 +-- docs/agents/issue-tracker.md | 30 ------------------- .../spec.md => docs/specs/protocol-probe.md | 0 .../spec.md => docs/specs/proxyctl-v1.md | 2 -- .../spec.md => docs/specs/tui-redesign.md | 2 -- 25 files changed, 2 insertions(+), 429 deletions(-) delete mode 100644 .scratch/proxyctl/issues/01-persistent-proxy-profiles.md delete mode 100644 .scratch/proxyctl/issues/02-shell-target.md delete mode 100644 .scratch/proxyctl/issues/03-apt-target.md delete mode 100644 .scratch/proxyctl/issues/04-docker-containers-target.md delete mode 100644 .scratch/proxyctl/issues/05-gnome-target.md delete mode 100644 .scratch/proxyctl/issues/06-docker-daemon-target.md delete mode 100644 .scratch/proxyctl/issues/07-diagnostics-and-reset.md delete mode 100644 .scratch/proxyctl/issues/08-coordinate-target-panel.md delete mode 100644 .scratch/proxyctl/issues/09-release-v1.md delete mode 100644 .scratch/tui-redesign/issues/01-responsive-tui-foundation.md delete mode 100644 .scratch/tui-redesign/issues/02-operations-console-dashboard.md delete mode 100644 .scratch/tui-redesign/issues/03-progressive-startup-and-refresh.md delete mode 100644 .scratch/tui-redesign/issues/04-operation-coordination-and-status.md delete mode 100644 .scratch/tui-redesign/issues/05-contextual-target-actions.md delete mode 100644 .scratch/tui-redesign/issues/06-active-profile-picker.md delete mode 100644 .scratch/tui-redesign/issues/07-profile-management-page.md delete mode 100644 .scratch/tui-redesign/issues/08-profile-editor.md delete mode 100644 .scratch/tui-redesign/issues/09-protocol-probe-field-action.md delete mode 100644 .scratch/tui-redesign/issues/10-help-dialog-and-navigation.md delete mode 100644 .scratch/tui-redesign/issues/11-accessibility-privacy-render-hardening.md delete mode 100644 docs/agents/issue-tracker.md rename .scratch/protocol-probe/spec.md => docs/specs/protocol-probe.md (100%) rename .scratch/proxyctl/spec.md => docs/specs/proxyctl-v1.md (99%) rename .scratch/tui-redesign/spec.md => docs/specs/tui-redesign.md (99%) diff --git a/.scratch/proxyctl/issues/01-persistent-proxy-profiles.md b/.scratch/proxyctl/issues/01-persistent-proxy-profiles.md deleted file mode 100644 index 700feee..0000000 --- a/.scratch/proxyctl/issues/01-persistent-proxy-profiles.md +++ /dev/null @@ -1,18 +0,0 @@ -# 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:** done - -- [ ] 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. diff --git a/.scratch/proxyctl/issues/02-shell-target.md b/.scratch/proxyctl/issues/02-shell-target.md deleted file mode 100644 index 23923b2..0000000 --- a/.scratch/proxyctl/issues/02-shell-target.md +++ /dev/null @@ -1,20 +0,0 @@ -# 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:** done - -- [ ] 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. diff --git a/.scratch/proxyctl/issues/03-apt-target.md b/.scratch/proxyctl/issues/03-apt-target.md deleted file mode 100644 index 477d1c3..0000000 --- a/.scratch/proxyctl/issues/03-apt-target.md +++ /dev/null @@ -1,18 +0,0 @@ -# 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:** done - -- [ ] 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. diff --git a/.scratch/proxyctl/issues/04-docker-containers-target.md b/.scratch/proxyctl/issues/04-docker-containers-target.md deleted file mode 100644 index fd48008..0000000 --- a/.scratch/proxyctl/issues/04-docker-containers-target.md +++ /dev/null @@ -1,18 +0,0 @@ -# 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:** done - -- [ ] 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. diff --git a/.scratch/proxyctl/issues/05-gnome-target.md b/.scratch/proxyctl/issues/05-gnome-target.md deleted file mode 100644 index 56eca94..0000000 --- a/.scratch/proxyctl/issues/05-gnome-target.md +++ /dev/null @@ -1,18 +0,0 @@ -# 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:** done - -- [ ] 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. diff --git a/.scratch/proxyctl/issues/06-docker-daemon-target.md b/.scratch/proxyctl/issues/06-docker-daemon-target.md deleted file mode 100644 index 1e2347e..0000000 --- a/.scratch/proxyctl/issues/06-docker-daemon-target.md +++ /dev/null @@ -1,19 +0,0 @@ -# 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:** done - -- [ ] 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. diff --git a/.scratch/proxyctl/issues/07-diagnostics-and-reset.md b/.scratch/proxyctl/issues/07-diagnostics-and-reset.md deleted file mode 100644 index c49eba2..0000000 --- a/.scratch/proxyctl/issues/07-diagnostics-and-reset.md +++ /dev/null @@ -1,18 +0,0 @@ -# 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:** done - -- [ ] `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. diff --git a/.scratch/proxyctl/issues/08-coordinate-target-panel.md b/.scratch/proxyctl/issues/08-coordinate-target-panel.md deleted file mode 100644 index 7e55fa0..0000000 --- a/.scratch/proxyctl/issues/08-coordinate-target-panel.md +++ /dev/null @@ -1,20 +0,0 @@ -# 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:** done - -- [ ] 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. diff --git a/.scratch/proxyctl/issues/09-release-v1.md b/.scratch/proxyctl/issues/09-release-v1.md deleted file mode 100644 index db76630..0000000 --- a/.scratch/proxyctl/issues/09-release-v1.md +++ /dev/null @@ -1,18 +0,0 @@ -# 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:** done - -- [ ] `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. diff --git a/.scratch/tui-redesign/issues/01-responsive-tui-foundation.md b/.scratch/tui-redesign/issues/01-responsive-tui-foundation.md deleted file mode 100644 index a1344f5..0000000 --- a/.scratch/tui-redesign/issues/01-responsive-tui-foundation.md +++ /dev/null @@ -1,19 +0,0 @@ -# 01 — Build the responsive TUI foundation - -**What to build:** Replace the current unbounded terminal document with a responsive, styled application shell that preserves the existing reachable workflows while establishing the layout, theme, redaction, and page seams required by the redesign. - -**Blocked by:** None — can start immediately. - -**Status:** done - -- [x] Bubble Tea remains the runtime, with Bubbles and Lip Gloss available as direct production dependencies. -- [x] Production runs in the terminal alternate screen and restores the previous screen on normal exit. -- [x] The complete TUI Model handles terminal resize messages and renders a usable wide layout at 120×36. -- [x] The same Model renders a usable single-column layout at 80×24. -- [x] Terminals below 60×16 render a concise minimum-size message instead of a corrupted interface. -- [x] Selection and focus survive resize whenever their referenced item still exists. -- [x] Semantic styling supports light, dark, and `NO_COLOR` rendering without making color the only signal. -- [x] All text entering the presentation layer crosses one defensive credential-redaction path. -- [x] Application coordination, responsive layout, semantic theme, pages, and reusable rendering no longer accumulate in one monolithic implementation. -- [x] Existing Target and Proxy Profile workflows remain reachable; no long-lived legacy/new TUI switch is introduced. -- [x] Complete-Model tests cover the three agreed terminal-size classes. diff --git a/.scratch/tui-redesign/issues/02-operations-console-dashboard.md b/.scratch/tui-redesign/issues/02-operations-console-dashboard.md deleted file mode 100644 index 5b2e3fe..0000000 --- a/.scratch/tui-redesign/issues/02-operations-console-dashboard.md +++ /dev/null @@ -1,20 +0,0 @@ -# 02 — Deliver the Operations Console dashboard - -**What to build:** Give users the accepted Operations Console experience: a stable, scannable Target list and concise selected-Target details, side by side on wide terminals and stacked on narrow terminals. - -**Blocked by:** 01 — Build the responsive TUI foundation. - -**Status:** done - -- [x] The header shows a compact proxyctl identity, the Active Profile, and counts for the current Target states. -- [x] Available Targets appear in stable product order by default. -- [x] A contextual action reveals unavailable Targets and their detection evidence without changing product order. -- [x] Each Target row combines a standard Unicode/ASCII-safe symbol, explicit state text, and semantic styling. -- [x] The selected Target details prioritize state, evidence, affected scope, permissions, ownership/restoration implications, and restart risk. -- [x] Wide terminals show Target list and details panes side by side; narrow terminals stack the same regions. -- [x] Tab changes pane focus, the focused pane is visible without relying only on color, and arrows navigate within the focused pane. -- [x] Long Target lists and details remain reachable through list/viewport scrolling. -- [x] The footer shows only actions valid for the current focus and state. -- [x] Resizing preserves selection by Target identity rather than fragile row position. -- [x] Complete-Model tests cover every Target state, unavailable visibility, long content, focus, scrolling, and wide/narrow rendering. -- [x] Production rendering is rewritten from the spec; prototype branch `prototype/tui-operations-console` commit `364f28d` is reference material only and is not copied into production. diff --git a/.scratch/tui-redesign/issues/03-progressive-startup-and-refresh.md b/.scratch/tui-redesign/issues/03-progressive-startup-and-refresh.md deleted file mode 100644 index 028ddcf..0000000 --- a/.scratch/tui-redesign/issues/03-progressive-startup-and-refresh.md +++ /dev/null @@ -1,23 +0,0 @@ -# 03 — Stream progressive startup and refresh - -**What to build:** Show the dashboard immediately and update each Target independently as detection completes, both at startup and when the user refreshes. - -**Blocked by:** 02 — Deliver the Operations Console dashboard. - -**Status:** done - -- [x] Interactive application construction exposes Target identity and descriptions before availability and inspection complete. -- [x] Startup renders every known Target in a structured Checking state without waiting for aggregate detection. -- [x] Availability and inspection results stream to the TUI one Target at a time. -- [x] Refresh uses the same progressive behavior rather than a separate aggregate-only path. -- [x] Checking rows display a non-color-only progress cue and update independently on success or failure. -- [x] Independent completion order does not reorder Targets or move selection to a different identity. -- [x] A Target detection failure is represented truthfully without preventing unrelated Target results from appearing. -- [x] The progressive Application Interface contains presentation-independent phases and results rather than Bubble Tea types or strings that callers must parse. -- [x] Existing non-interactive maintenance behavior remains compatible. -- [x] Application tests cover independent completion order, mixed success/failure, and final snapshots. -- [x] Complete-Model tests prove the first useful frame precedes detection completion and each subsequent result updates only the relevant row. - -## Answer - -Progressive startup and refresh now publish authoritative Application snapshots per Target while generation checks discard stale overlapping results. Application state and snapshots share one lock, dispatch invalidates in-flight detection before committing mutations, and the dashboard retains selected Target identity—including a newly unavailable selected Target. Adapter detection failures are classified truthfully without changing maintenance inspection semantics. diff --git a/.scratch/tui-redesign/issues/04-operation-coordination-and-status.md b/.scratch/tui-redesign/issues/04-operation-coordination-and-status.md deleted file mode 100644 index d7c4012..0000000 --- a/.scratch/tui-redesign/issues/04-operation-coordination-and-status.md +++ /dev/null @@ -1,21 +0,0 @@ -# 04 — Unify operation coordination and status feedback - -**What to build:** Give every interactive operation one coherent model for progress, serialization, confirmations, current status, partial failure, and safe exit while keeping the dashboard browsable. - -**Blocked by:** 03 — Stream progressive startup and refresh. - -**Status:** done - -- [x] Detection, Target mutation, and Active Profile transition use one presentation-independent progressive operation contract where their semantics overlap. -- [x] System mutations remain serialized and a conflicting action exposes an actionable disabled reason instead of silently ignoring input. -- [x] During a mutation, users can still select Targets, scroll details, and open existing read-only Help. -- [x] The affected Target row displays progress while the status area describes the current step. -- [x] Successful status is replaceable by later activity. -- [x] Current errors remain visible until acknowledged, superseded by explicit resolution, or replaced by a directly related result. -- [x] Current error details can be expanded without introducing an activity-history page. -- [x] Partial Active Profile transitions retain successful Target updates, preserve the no-cross-Target-rollback rule, and focus the first failed Target. -- [x] Confirmation state, progress, and final result are structured; the TUI does not parse user-facing strings to infer operation state. -- [x] `q` on the dashboard and Ctrl+C on any page request exit; during a mutation the UI visibly reports deferred exit and exits only after safe completion. -- [x] No new work can begin after deferred exit is requested. -- [x] The concrete Application remains usable by existing synchronous callers while obsolete interactive fallback paths are removed after migration. -- [x] Application and complete-Model tests cover browsing while busy, blocked mutations, persistent errors, partial failure, confirmation, and deferred exit. diff --git a/.scratch/tui-redesign/issues/05-contextual-target-actions.md b/.scratch/tui-redesign/issues/05-contextual-target-actions.md deleted file mode 100644 index b5c3629..0000000 --- a/.scratch/tui-redesign/issues/05-contextual-target-actions.md +++ /dev/null @@ -1,24 +0,0 @@ -# 05 — Add contextual Target actions and Drift Resolution - -**What to build:** Replace the ambiguous Target toggle with actions that reflect the selected Target's real state, including explicit Drift Resolution choices. - -**Blocked by:** 04 — Unify operation coordination and status feedback. - -**Status:** done - -- [x] A Disabled Target offers Enable. -- [x] An Enabled Target offers Disable. -- [x] An External Target offers Apply Profile and explains that proxyctl will begin managing the configuration while preserving restorable state. -- [x] A Drifted Target offers Resolve rather than silently choosing a direction. -- [x] Drift Resolution offers Reapply Active Profile and Restore Original as separate intents. -- [x] Reapply uses the Active Profile and returns truthful Enabled, Drifted, or failure state. -- [x] Restore Original reuses existing ownership safeguards and refuses safely when restoration evidence is insufficient. -- [x] No Adapter ownership, restoration, or cross-Target rollback semantics are weakened. -- [x] Docker restart confirmation remains required for relevant actions and cancellation is the default focused choice. -- [x] Routine reversible actions do not gain new confirmation dialogs. -- [x] Action availability and disabled reasons are structured in the Application snapshot rather than inferred from rendered labels. -- [x] Application and complete-Model tests cover all Target states, both Drift Resolution branches, missing Active Profile, ownership loss, confirmation, and cancellation without mutation. - -## Answer - -The Application snapshot now exposes contextual Target actions and Drift Resolution choices as structured availability plus disabled reasons. Dispatch revalidates every Target intent against that current structure immediately before confirmation or `SetDesired`, so stale, checking, failed, unavailable, profile-dependent, and ownership-sensitive intents fail without unsafe mutation. Reapply and Restore retain Adapter `SetDesired` semantics and existing restoration safeguards, while the complete Model preserves explicit resolution and safe-default confirmation/cancellation behavior. diff --git a/.scratch/tui-redesign/issues/06-active-profile-picker.md b/.scratch/tui-redesign/issues/06-active-profile-picker.md deleted file mode 100644 index af466cf..0000000 --- a/.scratch/tui-redesign/issues/06-active-profile-picker.md +++ /dev/null @@ -1,19 +0,0 @@ -# 06 — Add the searchable Active Profile picker - -**What to build:** Let users search for and activate a Proxy Profile directly from the dashboard without mixing routine switching with Profile management. - -**Blocked by:** 02 — Deliver the Operations Console dashboard; 04 — Unify operation coordination and status feedback. - -**Status:** done - -- [x] A dashboard action opens a keyboard-only modal Profile picker. -- [x] The Active Profile is pinned first and all remaining Profiles are sorted by name. -- [x] The picker supports filtering and scrolling across more Profiles than fit in the terminal. -- [x] Enter activates the selected Profile and Escape closes the picker without mutation. -- [x] Activation uses the unified progressive operation contract and displays per-Target progress on the dashboard. -- [x] Docker restart confirmation appears when required, with cancellation as the safe default. -- [x] Partial failure retains successful Target updates, closes or preserves the picker predictably, and focuses the first failed Target. -- [x] Search text and selection survive resize when the selected Profile still exists. -- [x] Empty and no-match states provide clear next actions without conflating switching with creation. -- [x] Profile names and all operation text are defensively redacted before rendering. -- [x] Complete-Model tests cover ordering, search, keyboard selection, resize, activation, confirmation, cancellation, partial failure, and empty states. diff --git a/.scratch/tui-redesign/issues/07-profile-management-page.md b/.scratch/tui-redesign/issues/07-profile-management-page.md deleted file mode 100644 index 5e90f43..0000000 --- a/.scratch/tui-redesign/issues/07-profile-management-page.md +++ /dev/null @@ -1,19 +0,0 @@ -# 07 — Build the dedicated Profile management page - -**What to build:** Provide a scrollable keyboard-first page for creating, editing, reviewing, and deleting Proxy Profiles while keeping activation in the dashboard picker. - -**Blocked by:** 01 — Build the responsive TUI foundation; 04 — Unify operation coordination and status feedback. - -**Status:** done - -- [x] Profile management is a distinct page from the dashboard activation picker. -- [x] The Profile list scrolls and keeps selection visible with more entries than fit on screen. -- [x] The selected Profile's mode, obscured URLs, and Bypass values are reviewable without exposing credentials. -- [x] Create, edit, and delete entry points are available through contextual keyboard actions. -- [x] Deletion uses a reusable confirmation dialog with cancellation focused by default. -- [x] Deleting the final Proxy Profile clearly explains that existing managed configuration remains and becomes Drifted. -- [x] Escape and `q` return to the previous page; Ctrl+C follows the global exit contract. -- [x] Operations disabled by in-flight work expose a reason rather than silently ignoring input. -- [x] Selection and viewport survive resize and CRUD results whenever the referenced Profile still exists. -- [x] Empty-state copy provides a direct creation path and does not incorrectly claim no Active Profile when non-active Profiles exist. -- [x] Complete-Model tests cover long lists, details, create/edit entry, deletion confirmation, final deletion, cancellation, resize, and navigation consistency. diff --git a/.scratch/tui-redesign/issues/08-profile-editor.md b/.scratch/tui-redesign/issues/08-profile-editor.md deleted file mode 100644 index 8ca2572..0000000 --- a/.scratch/tui-redesign/issues/08-profile-editor.md +++ /dev/null @@ -1,19 +0,0 @@ -# 08 — Deliver the mature Profile editor - -**What to build:** Replace append-only Profile editing with efficient terminal text inputs, precise validation, and a live Bypass interpretation that users can trust before saving. - -**Blocked by:** 07 — Build the dedicated Profile management page. - -**Status:** done - -- [x] Name and URL fields support insertion, cursor movement, Home, End, Delete, Backspace, paste, and horizontal scrolling. -- [x] Focus is explicit and remains understandable without color. -- [x] Single and Advanced mode transitions preserve values according to existing Proxy Profile semantics. -- [x] Field-specific validation appears beside the relevant field and updates when input changes. -- [x] Save uses the same canonical Profile validation semantics as the live feedback, preventing contradictory results. -- [x] Bypass accepts efficient delimited input and displays a live normalized, deduplicated preview. -- [x] Invalid Bypass entries are identified individually without hiding valid entries. -- [x] Proxy credentials remain obscured during entry, scrolling, validation, review, errors, and resize. -- [x] Save returns to management with the saved Profile selected; cancel leaves persistence unchanged. -- [x] Long URLs and Bypass content remain usable at 80×24. -- [x] Complete-Model tests cover editing operations, paste, horizontal scrolling, mode transitions, validation lifecycle, Bypass preview, save, cancel, resize, and adversarial secret-bearing input. diff --git a/.scratch/tui-redesign/issues/09-protocol-probe-field-action.md b/.scratch/tui-redesign/issues/09-protocol-probe-field-action.md deleted file mode 100644 index 1b0ff97..0000000 --- a/.scratch/tui-redesign/issues/09-protocol-probe-field-action.md +++ /dev/null @@ -1,19 +0,0 @@ -# 09 — Attach Protocol Probe to the Profile field - -**What to build:** Make Protocol Probe an explicit, user-initiated URL-field action whose progress and result remain attached to the input that produced them. - -**Blocked by:** 08 — Deliver the mature Profile editor. - -**Status:** done - -- [x] The applicable URL field visibly offers Protocol Probe and documents its keyboard shortcut. -- [x] Probe never runs when the form opens, when focus changes, or when a Profile is saved. -- [x] Progress, endpoint-safe status, and detected capabilities render with the initiating field rather than as unrelated global status. -- [x] HTTP-only detection populates the established HTTP representation. -- [x] SOCKS5-only detection preserves the established `socks5h` semantics. -- [x] Dual HTTP/SOCKS5 detection creates the established compatible Advanced Profile values. -- [x] Editing the relevant URL, changing mode, saving, or cancelling invalidates an in-flight result. -- [x] Repeated invocation while the same probe is active does not start duplicate work. -- [x] Userinfo and credentials never appear in dial evidence, status, errors, or rendered frames. -- [x] Failure and unrecognized-protocol results leave user input editable and do not prevent saving a manually chosen value. -- [x] Complete-Model tests cover all capabilities, failure, explicit invocation, no hidden network work, duplicate suppression, resize, and every stale-result path. diff --git a/.scratch/tui-redesign/issues/10-help-dialog-and-navigation.md b/.scratch/tui-redesign/issues/10-help-dialog-and-navigation.md deleted file mode 100644 index 46adf5c..0000000 --- a/.scratch/tui-redesign/issues/10-help-dialog-and-navigation.md +++ /dev/null @@ -1,19 +0,0 @@ -# 10 — Unify Help, dialogs, and navigation - -**What to build:** Give every page a consistent keyboard navigation and modal model, with scrollable contextual Help that can be consulted without losing current work. - -**Blocked by:** 04 — Unify operation coordination and status feedback; 07 — Build the dedicated Profile management page. - -**Status:** done - -- [x] Help opens as a scrollable contextual dialog over the current page rather than an unbounded static document. -- [x] Help describes actions valid for the current page, focus, Target state, and operation state. -- [x] Escape closes the top dialog or returns one page level. -- [x] `q` returns from child pages and exits only from the dashboard. -- [x] Ctrl+C requests exit from every page and follows deferred-exit safety during mutations. -- [x] Closing a dialog restores the prior page, focus, selection, and viewport when still valid. -- [x] Dialog stacking and confirmation precedence are deterministic; an input cannot accidentally act on content behind a dialog. -- [x] Dialogs resize within the agreed terminal bounds and preserve meaningful focus. -- [x] Help can be opened and scrolled during a mutation while conflicting actions remain disabled. -- [x] Footer hints agree with actual accepted keys, including cancel and back behavior. -- [x] Complete-Model tests cover Help from every page, long Help, nested dialog precedence, resize, focus restoration, `q`, Escape, Ctrl+C, and in-flight operation behavior. diff --git a/.scratch/tui-redesign/issues/11-accessibility-privacy-render-hardening.md b/.scratch/tui-redesign/issues/11-accessibility-privacy-render-hardening.md deleted file mode 100644 index 24929c2..0000000 --- a/.scratch/tui-redesign/issues/11-accessibility-privacy-render-hardening.md +++ /dev/null @@ -1,24 +0,0 @@ -# 11 — Harden accessibility, privacy, and rendering - -**What to build:** Verify and finish the redesigned TUI across supported terminal sizes, color modes, hostile text, and process lifecycle so that visual polish does not compromise meaning, privacy, or reliability. - -**Blocked by:** 03 — Stream progressive startup and refresh; 04 — Unify operation coordination and status feedback; 05 — Add contextual Target actions and Drift Resolution; 06 — Add the searchable Active Profile picker; 07 — Build the dedicated Profile management page; 08 — Deliver the mature Profile editor; 09 — Attach Protocol Probe to the Profile field; 10 — Unify Help, dialogs, and navigation. - -**Status:** done - -- [x] Fixed-size render coverage includes 120×36, 80×24, and 59×15 across the completed workflows. -- [x] Light, dark, and `NO_COLOR` renders retain readable state, focus, progress, warnings, disabled actions, and errors. -- [x] Standard Unicode symbols have a safe rendering strategy and no Nerd Font dependency. -- [x] Long Target names, Profile names, evidence, details, URLs, Bypass values, errors, and confirmation copy remain bounded and reachable. -- [x] Secrets injected through valid and malformed Profile fields, evidence, notices, errors, progress, command output, and confirmations never appear in any rendered frame. -- [x] Resize stress preserves valid page, dialog, focus, selection, viewport, in-flight operation, and deferred-exit state. -- [x] Alternate-screen process tests verify normal exit and safe deferred exit restore the prior terminal screen. -- [x] Startup, refresh, Target action, Active Profile switching, management, editor, Probe, Help, and Drift Resolution each have complete-Model behavioral coverage. -- [x] Tests assert semantic behavior rather than private component structure or raw styling calls. -- [x] Existing Application and Adapter suites remain green without duplicating Target configuration tests in the TUI. -- [x] Documentation describes the redesigned keyboard model, responsive size behavior, Profile switching, contextual Target actions, and privacy boundaries. -- [x] Full repository and hermetic verification pass without modifying real Shell, APT, Docker, GNOME, or systemd state. - -## Answer - -Final hardening now exercises every completed workflow through the production Model at all supported size classes, checks semantic equivalence across light, dark, and `NO_COLOR`, uses cell-width bounds for Unicode content, rejects private-use/Nerd Font glyphs, and preserves complete interaction state through resize stress. Every untrusted ingress is credential-redacted and stripped of terminal controls before semantic styling; the final frame pass only validates controls and does not reparse clipped prose. Long fields, Bypass previews, errors, and arbitrary confirmation copy remain scrollable through resize at nonterminal offsets. Real subprocess tests under a PTY prove alternate-screen restoration after normal exit and after exit is deferred for an already-blocked Target mutation. Unprivileged hermetic verification hashes all readable host paths and compares stable metadata plus explicit markers for protected paths without sudo. README documents the final keyboard, responsive, contextual-action, accessibility, lifecycle, and privacy contracts. diff --git a/AGENTS.md b/AGENTS.md index e060511..3f20f8b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,8 +1,8 @@ ## Agent skills -### Issue tracker +### Issue tracking -Issues are tracked as local Markdown files under `.scratch/`. See `docs/agents/issue-tracker.md`. +Issues are managed in the repository's Gitea issue tracker. Use `tea` for issue operations; do not create local ticket trees. Long-lived product and design specifications belong under `docs/specs/`. ### Domain docs diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md deleted file mode 100644 index cb96da3..0000000 --- a/docs/agents/issue-tracker.md +++ /dev/null @@ -1,30 +0,0 @@ -# Issue tracker: Local Markdown - -Issues and specs for this repo live as Markdown files in `.scratch/`. - -## Conventions - -- One feature per directory: `.scratch//` -- The spec is `.scratch//spec.md` -- Implementation issues are one file per ticket at - `.scratch//issues/-.md` -- Tickets are numbered from `01` -- Comments and conversation history are appended under `## Comments` - -## When a skill says "publish to the issue tracker" - -Create a new file under `.scratch//`, creating the directory if needed. - -## When a skill says "fetch the relevant ticket" - -Read the referenced file. The user will normally provide its path or issue number. - -## Wayfinding operations - -- Map: `.scratch//map.md` -- Child ticket: `.scratch//issues/NN-.md` -- `Type:` records `research`, `prototype`, `grilling`, or `task` -- `Status:` records `claimed` or `resolved` -- `Blocked by: NN, NN` declares blocking relationships -- Claim a ticket by setting `Status: claimed` -- Resolve it by adding `## Answer`, setting `Status: resolved`, and updating the map diff --git a/.scratch/protocol-probe/spec.md b/docs/specs/protocol-probe.md similarity index 100% rename from .scratch/protocol-probe/spec.md rename to docs/specs/protocol-probe.md diff --git a/.scratch/proxyctl/spec.md b/docs/specs/proxyctl-v1.md similarity index 99% rename from .scratch/proxyctl/spec.md rename to docs/specs/proxyctl-v1.md index b14b17b..6f824b6 100644 --- a/.scratch/proxyctl/spec.md +++ b/docs/specs/proxyctl-v1.md @@ -1,5 +1,3 @@ -Status: ready-for-agent - # proxyctl v1 specification ## Problem Statement diff --git a/.scratch/tui-redesign/spec.md b/docs/specs/tui-redesign.md similarity index 99% rename from .scratch/tui-redesign/spec.md rename to docs/specs/tui-redesign.md index 15eb964..c70e7c9 100644 --- a/.scratch/tui-redesign/spec.md +++ b/docs/specs/tui-redesign.md @@ -1,5 +1,3 @@ -Status: ready-for-agent - # Efficient professional TUI redesign ## Problem Statement