Polish poolctl for public use

.github/workflows/tests.yml

@@ -0,0 +1,26 @@
+name: tests
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  pytest:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install -e ".[dev]"
+      - run: test -x script/install && sh -n script/install
+      - run: ruff format --check poolctl tests
+      - run: ruff check poolctl tests
+      - run: detect-secrets scan --baseline .secrets.baseline
+      - run: pytest -q

.gitignore

@@ -1,8 +1,12 @@
 .venv/
 __pycache__/
 .pytest_cache/
-*.pyc
+*.py[cod]
 *.egg-info/
 .env
 .vscode/
 .idea/
+.ruff_cache/
+config/adapter.json
+build/
+dist/

.secrets.baseline

@@ -0,0 +1,139 @@
+{
+  "version": "1.5.0",
+  "plugins_used": [
+    {
+      "name": "ArtifactoryDetector"
+    },
+    {
+      "name": "AWSKeyDetector"
+    },
+    {
+      "name": "AzureStorageKeyDetector"
+    },
+    {
+      "name": "Base64HighEntropyString",
+      "limit": 4.5
+    },
+    {
+      "name": "BasicAuthDetector"
+    },
+    {
+      "name": "CloudantDetector"
+    },
+    {
+      "name": "DiscordBotTokenDetector"
+    },
+    {
+      "name": "GitHubTokenDetector"
+    },
+    {
+      "name": "GitLabTokenDetector"
+    },
+    {
+      "name": "HexHighEntropyString",
+      "limit": 3.0
+    },
+    {
+      "name": "IbmCloudIamDetector"
+    },
+    {
+      "name": "IbmCosHmacDetector"
+    },
+    {
+      "name": "IPPublicDetector"
+    },
+    {
+      "name": "JwtTokenDetector"
+    },
+    {
+      "name": "KeywordDetector",
+      "keyword_exclude": ""
+    },
+    {
+      "name": "MailchimpDetector"
+    },
+    {
+      "name": "NpmDetector"
+    },
+    {
+      "name": "OpenAIDetector"
+    },
+    {
+      "name": "PrivateKeyDetector"
+    },
+    {
+      "name": "PypiTokenDetector"
+    },
+    {
+      "name": "SendGridDetector"
+    },
+    {
+      "name": "SlackDetector"
+    },
+    {
+      "name": "SoftlayerDetector"
+    },
+    {
+      "name": "SquareOAuthDetector"
+    },
+    {
+      "name": "StripeDetector"
+    },
+    {
+      "name": "TelegramBotTokenDetector"
+    },
+    {
+      "name": "TwilioKeyDetector"
+    }
+  ],
+  "filters_used": [
+    {
+      "path": "detect_secrets.filters.allowlist.is_line_allowlisted"
+    },
+    {
+      "path": "detect_secrets.filters.common.is_baseline_file",
+      "filename": ".secrets.baseline"
+    },
+    {
+      "path": "detect_secrets.filters.common.is_ignored_due_to_verification_policies",
+      "min_level": 2
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_indirect_reference"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_likely_id_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_lock_file"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_not_alphanumeric_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_potential_uuid"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_prefixed_with_dollar_sign"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_sequential_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_swagger_file"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_templated_secret"
+    },
+    {
+      "path": "detect_secrets.filters.regex.should_exclude_file",
+      "pattern": [
+        "^\\.git/",
+        "^docs/assets/",
+        "^\\.secrets\\.baseline$"
+      ]
+    }
+  ],
+  "results": {},
+  "generated_at": "2026-08-16T20:10:38Z"
+}

AGENTS.md

@@ -1,72 +1,41 @@
-# AGENTS.md
-
-## What this repo is
-
-`poolctl` is a terminal-first Pentair ScreenLogic exploration and control project.
-
-The goal is not to build a bloated smart-home platform on day one. The goal is to build:
-- a clean library layer
-- a sharp CLI
-- small, understandable commands
-- enough protocol understanding to control real hardware safely
-
-Think: UNIX tool, not enterprise sludge.
-
-## Project principles
-
-- **Library first, CLI immediately useful.**
-  The protocol/control logic should be reusable, while the CLI stays pleasant for direct human use.
-
-- **Read before write.**
-  Prefer adding discovery, inventory, and state inspection before mutating commands.
-
-- **Small commands, low surprise.**
-  Commands should do one thing well and print useful output.
-
-- **Test the rendering and logic layers.**
-  Unit tests should cover summary/formatting/helpers even when live hardware tests are limited.
-
-- **Treat live pool hardware with respect.**
-  Avoid risky or surprising writes. Add guardrails around mutating commands.
-
-- **Hide vendor friction only when explicitly desired.**
-  Prefer small sharp commands over over-smart orchestration. Keep cleaner control and delay cancellation as separate explicit commands unless the user wants otherwise.
-
-- **Update docs when the shape settles.**
-  When a change feels right, update `README.md` and `AGENTS.md` in the same stretch of work. Clean code and current docs go together.
-
-- **Prefer pipx for installed CLI usage.**
-  For daily use, these tools should behave like normal commands on the user path. Reserve local venv activation for development and testing.
-
-## Current shape
-
-- `poolctl/gateway.py` — adapter discovery, cached adapter resolution, and live status fetch
-- `poolctl/config.py` — tiny config/cache for adapter connection details
+# Repository guidance
+
+## Purpose
+
+`poolctl` is a terminal-first Pentair ScreenLogic inspection and control tool.
+Keep the reusable protocol/control layer separate from presentation, and keep
+the installed CLI useful without requiring repository knowledge.
+
+## Engineering principles
+
+- Read state before adding or performing a write.
+- Keep commands small, explicit, and scriptable.
+- Treat live pool hardware as safety-sensitive.
+- Require a deliberate guard for every mutating command.
+- Report post-write state instead of equating request acceptance with success.
+- Keep real adapter names, IPs, and site topology outside the public repository.
+- Preserve compact human output and stable JSON output.
+- Test pure selection, rendering, configuration, and protocol logic without
+  requiring live hardware.
+- Update `README.md`, `SKILL.md`, and relevant files under `docs/` when command
+  behavior changes.
+- Maintain `script/install` as the language-neutral deployment contract. A
+  future Rust migration changes that script, not private bootstrap callers.
+
+## Layout
+
+- `poolctl/gateway.py` — discovery, cached adapter resolution, and status fetch
+- `poolctl/config.py` — private local adapter configuration
 - `poolctl/render.py` — summary shaping and human-readable output
-- `poolctl/control.py` — small explicit control helpers for cleaner and delay actions
-- `poolctl/protocol.py` — protocol gaps not covered by screenlogicpy
-- `poolctl/cli.py` — command-line entrypoint
-- `tests/` — unit tests for pure logic/rendering/config helpers
-
-`SKILL.md` lives at the repo root so Botty can use this CLI directly when Chris asks for pool actions in chat.
-
-## Near-term roadmap
-
-1. Keep the cleaner/delay interface sharp and boring
-2. Robust circuit lookup by name/id
-3. Better structured JSON output
-4. Add explicit config commands if useful (`config show`, maybe `config set-host`)
-5. Optional Rust port later if the Python shape proves right
-
-## Style
-
-- Keep code boring and readable.
-- Avoid needless framework energy.
-- Prefer explicit names over magic.
-- Don’t let the repo turn into app-store cosplay.
-
-## Vibe
-
-This project is a small terminal trident for poking a cursed pool box over the LAN.
-
-🌊🤖🔱
+- `poolctl/control.py` — guarded cleaner and delay helpers
+- `poolctl/protocol.py` — protocol behavior missing from `screenlogicpy`
+- `poolctl/cli.py` — command-line parser and dispatch
+- `script/install` — stable installer entry point for deployment automation
+- `tests/` — hardware-free unit tests
+- `docs/` — operations, protocol, troubleshooting, and roadmap notes
+
+## Development
+
+Prefer `pipx` for daily installed use and `.venv` for development. Run the full
+format, lint, secret-scan, and test sequence documented in `README.md` before
+publishing. Never make a live hardware write as part of an automated test.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Berry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.