hookstride-cli 0.2.0__tar.gz

hookstride_cli-0.2.0/.gitignore

@@ -0,0 +1,14 @@
+.env
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+db.sqlite3
+staticfiles/*
+!staticfiles/.gitkeep
+.DS_Store
+.idea/
+.vscode/

hookstride_cli-0.2.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.5
+Name: hookstride-cli
+Version: 0.2.0
+Summary: Readable, project-scoped Hookstride Control API terminal client.
+License: Proprietary
+Requires-Python: >=3.11
+Requires-Dist: click<9,>=8.1
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: prompt-toolkit<4,>=3.0.52
+Requires-Dist: rich<15,>=14
+Requires-Dist: typer<1,>=0.20
+Description-Content-Type: text/markdown
+
+# Hookstride CLI
+
+A fast, colorful, read-only terminal for the Hookstride Control API. Inspired by the clarity of tools like Nmap, it keeps ordinary REST responses unchanged for apps and integrations.
+
+## Install
+
+Once the first package release is available on PyPI, install with:
+
+```bash
+uv tool install hookstride-cli
+hookstride --version
+hookstride console
+```
+
+Alternative: `pipx install hookstride-cli`. Update with `uv tool upgrade hookstride-cli`.
+Requires Python 3.11 or newer. No checkout or Django backend installation is needed.
+
+## Authentication
+
+In the Hookstride dashboard, generate an MFA-verified **Control API / Management token**, beginning with `whrctl_`. Do **not** use a `whrk_` delivery API key, and never paste a token directly into commands or issue comments.
+
+The CLI reads `HOOKSTRIDE_CONTROL_TOKEN` from your current shell; it **does not persist tokens** on disk. For a Bash/Zsh terminal, paste interactively without writing the token in your command history:
+
+```bash
+printf "Control token: "
+read -rs HOOKSTRIDE_CONTROL_TOKEN
+printf "\\n"
+export HOOKSTRIDE_CONTROL_TOKEN
+
+hookstride auth status
+```
+
+The token may remain in your shell environment until you run `unset HOOKSTRIDE_CONTROL_TOKEN`. Environment values may be inspectable by processes with the appropriate local privileges; use an ephemeral, limited-life management token. Avoid recording terminal sessions while entering secrets.
+
+## Explore development
+
+```bash
+hookstride status
+hookstride auth status
+hookstride projects list
+hookstride projects use 00000000-0000-0000-0000-000000000000
+
+hookstride destinations list
+hookstride keys list
+hookstride incoming sources
+hookstride incoming routes
+hookstride incoming bindings
+hookstride incoming registration-keys
+hookstride events list --status failed
+hookstride events show 00000000-0000-0000-0000-000000000000
+hookstride stats
+hookstride billing status
+hookstride billing history
+hookstride config show
+```
+
+Replace the sample UUIDs with your own project/event IDs.
+
+The CLI starts on `https://api-dev.hookstride.voteeasy.net`. Use `--env production` (before the command) to target `https://api.hookstride.voteeasy.net`; configure each environment with its own corresponding Control token. The apex `https://hookstride.voteeasy.net` serves the frontend. You can also use `--api-url https://your-api-host` for a custom origin, or HTTP on loopback for local testing.
+
+**Project selection is environment-specific.** The only persisted data is a project UUID in `~/.config/hookstride/settings.json`, owner-readable; not your credentials. Override temporarily with `--project PROJECT_UUID`.
+
+## Development checks
+
+When the GitHub Actions runner is unavailable, run the **same** CLI tests locally
+without sending anything to the live Hookstride API:
+
+```bash
+bash cli/scripts/check.sh
+```
+
+This checks Python syntax, Ruff, isolated unit tests using mocked HTTP responses,
+and basic commands. A successful local run is not a substitute for a live
+read-only smoke test against the deployed development API.
+
+Tables use compact, borderless columns. Identifiers and long URLs are shortened
+only when necessary to fit the terminal; the actual API response is not changed.
+Use `--json` to copy complete project IDs, payment references and destination URLs.
+
+## Interactive operator console (v0.2)
+
+Start a lightweight, Metasploit-inspired, **read-only** interactive console:
+
+```bash
+hookstride console
+```
+
+The shell starts on the **development API** by default. Enter `help` for
+available commands, use Tab for completion, Ctrl+C to cancel the current line,
+and Ctrl+D or `exit` to close the console.
+
+```text
+HOOKSTRIDE CONSOLE v0.2
+hookstride [dev] > auth login
+Control token (hidden):
+✓ Authenticated as developer@example.com
+hookstride [dev] > show projects
+Projects
+========
+Name        Workspace     Role   Plan    Project ID
+----------  ------------  -----  ------  ------------------------------------
+Production  Beta Testing  owner  flex    ddc21845-d0f1-49af-8d35-2719dc641f69
+
+hookstride [dev] > use ddc21845-d0f1-49af-8d35-2719dc641f69
+hookstride [dev:ddc21845] > show payments
+hookstride [dev:ddc21845] > events list --status failed
+hookstride [dev:ddc21845] > show destinations
+hookstride [dev:ddc21845] > json events list
+hookstride [dev:ddc21845] > back
+hookstride [dev] > exit
+```
+
+This console accepts the existing read-only CLI commands, plus convenient
+`show` aliases, `set env dev|production`, `use UUID`,
+`back`, `clear`, `history`, and `auth login|logout`.
+`projects use UUID` and `use UUID` persist only the active project's UUID
+in local settings. The console does not support a shell escape, external
+processes, POST/DELETE operations, or purchases.
+
+### Token handling
+
+`auth login` securely prompts for a Control API token via hidden input. Tokens
+are kept **in memory for this console process only**, are discarded at exit,
+are never written to a config or history file, and are never echoed. The
+console stores only a **safe subset** of commands in volatile arrow-key history;
+it never records tokens or arbitrary query/search strings.
+
+You may also provide an existing token through environment variables:
+
+```bash
+# Use a development token with the default development console
+export HOOKSTRIDE_DEV_CONTROL_TOKEN="…"  # do not put real secrets in shell history
+hookstride console
+
+# To start directly against production, explicitly select it
+hookstride --env production console
+```
+
+For safest handling, prefer `auth login` over typing tokens in shell commands.
+For interactive environment changes, the generic legacy
+`HOOKSTRIDE_CONTROL_TOKEN` is **never forwarded to another environment**.
+Use `auth login` separately after `set env production`, or provide a
+matching `HOOKSTRIDE_PRODUCTION_CONTROL_TOKEN` token. This prevents a dev
+token from accidentally being sent to the production API.
+
+The console requires a real interactive terminal and refuses `--json console`.
+For CI and scripting, use ordinary commands such as
+`hookstride --json events list` instead.
+
+## Output for scripts
+
+Pass `--json` **before** the command:
+
+```bash
+hookstride --json projects list | jq .
+hookstride --json events list --status failed | jq '.results'
+hookstride --env production --json billing history
+```
+
+The raw structured response is printed to stdout without terminal formatting. Network and HTTP errors go to stderr and cause a nonzero exit status.
+
+## Scope
+
+Version 0.2 includes interactive access to project, destination, incoming-source, delivery-stat, activity and billing **reads**. It does not yet create destinations, emit events, replay events, rotate credentials, or trigger payments. Those workflows require additional confirmation and integration tests before exposing them in a CLI. Server-side authorization, project scoping, and response redaction remain enforced by the Control API.
+
+Do not store passwords, signing secrets, private keys, or Paystack keys in Hookstride CLI configuration.

hookstride_cli-0.2.0/README.md

@@ -0,0 +1,166 @@
+# Hookstride CLI
+
+A fast, colorful, read-only terminal for the Hookstride Control API. Inspired by the clarity of tools like Nmap, it keeps ordinary REST responses unchanged for apps and integrations.
+
+## Install
+
+Once the first package release is available on PyPI, install with:
+
+```bash
+uv tool install hookstride-cli
+hookstride --version
+hookstride console
+```
+
+Alternative: `pipx install hookstride-cli`. Update with `uv tool upgrade hookstride-cli`.
+Requires Python 3.11 or newer. No checkout or Django backend installation is needed.
+
+## Authentication
+
+In the Hookstride dashboard, generate an MFA-verified **Control API / Management token**, beginning with `whrctl_`. Do **not** use a `whrk_` delivery API key, and never paste a token directly into commands or issue comments.
+
+The CLI reads `HOOKSTRIDE_CONTROL_TOKEN` from your current shell; it **does not persist tokens** on disk. For a Bash/Zsh terminal, paste interactively without writing the token in your command history:
+
+```bash
+printf "Control token: "
+read -rs HOOKSTRIDE_CONTROL_TOKEN
+printf "\\n"
+export HOOKSTRIDE_CONTROL_TOKEN
+
+hookstride auth status
+```
+
+The token may remain in your shell environment until you run `unset HOOKSTRIDE_CONTROL_TOKEN`. Environment values may be inspectable by processes with the appropriate local privileges; use an ephemeral, limited-life management token. Avoid recording terminal sessions while entering secrets.
+
+## Explore development
+
+```bash
+hookstride status
+hookstride auth status
+hookstride projects list
+hookstride projects use 00000000-0000-0000-0000-000000000000
+
+hookstride destinations list
+hookstride keys list
+hookstride incoming sources
+hookstride incoming routes
+hookstride incoming bindings
+hookstride incoming registration-keys
+hookstride events list --status failed
+hookstride events show 00000000-0000-0000-0000-000000000000
+hookstride stats
+hookstride billing status
+hookstride billing history
+hookstride config show
+```
+
+Replace the sample UUIDs with your own project/event IDs.
+
+The CLI starts on `https://api-dev.hookstride.voteeasy.net`. Use `--env production` (before the command) to target `https://api.hookstride.voteeasy.net`; configure each environment with its own corresponding Control token. The apex `https://hookstride.voteeasy.net` serves the frontend. You can also use `--api-url https://your-api-host` for a custom origin, or HTTP on loopback for local testing.
+
+**Project selection is environment-specific.** The only persisted data is a project UUID in `~/.config/hookstride/settings.json`, owner-readable; not your credentials. Override temporarily with `--project PROJECT_UUID`.
+
+## Development checks
+
+When the GitHub Actions runner is unavailable, run the **same** CLI tests locally
+without sending anything to the live Hookstride API:
+
+```bash
+bash cli/scripts/check.sh
+```
+
+This checks Python syntax, Ruff, isolated unit tests using mocked HTTP responses,
+and basic commands. A successful local run is not a substitute for a live
+read-only smoke test against the deployed development API.
+
+Tables use compact, borderless columns. Identifiers and long URLs are shortened
+only when necessary to fit the terminal; the actual API response is not changed.
+Use `--json` to copy complete project IDs, payment references and destination URLs.
+
+## Interactive operator console (v0.2)
+
+Start a lightweight, Metasploit-inspired, **read-only** interactive console:
+
+```bash
+hookstride console
+```
+
+The shell starts on the **development API** by default. Enter `help` for
+available commands, use Tab for completion, Ctrl+C to cancel the current line,
+and Ctrl+D or `exit` to close the console.
+
+```text
+HOOKSTRIDE CONSOLE v0.2
+hookstride [dev] > auth login
+Control token (hidden):
+✓ Authenticated as developer@example.com
+hookstride [dev] > show projects
+Projects
+========
+Name        Workspace     Role   Plan    Project ID
+----------  ------------  -----  ------  ------------------------------------
+Production  Beta Testing  owner  flex    ddc21845-d0f1-49af-8d35-2719dc641f69
+
+hookstride [dev] > use ddc21845-d0f1-49af-8d35-2719dc641f69
+hookstride [dev:ddc21845] > show payments
+hookstride [dev:ddc21845] > events list --status failed
+hookstride [dev:ddc21845] > show destinations
+hookstride [dev:ddc21845] > json events list
+hookstride [dev:ddc21845] > back
+hookstride [dev] > exit
+```
+
+This console accepts the existing read-only CLI commands, plus convenient
+`show` aliases, `set env dev|production`, `use UUID`,
+`back`, `clear`, `history`, and `auth login|logout`.
+`projects use UUID` and `use UUID` persist only the active project's UUID
+in local settings. The console does not support a shell escape, external
+processes, POST/DELETE operations, or purchases.
+
+### Token handling
+
+`auth login` securely prompts for a Control API token via hidden input. Tokens
+are kept **in memory for this console process only**, are discarded at exit,
+are never written to a config or history file, and are never echoed. The
+console stores only a **safe subset** of commands in volatile arrow-key history;
+it never records tokens or arbitrary query/search strings.
+
+You may also provide an existing token through environment variables:
+
+```bash
+# Use a development token with the default development console
+export HOOKSTRIDE_DEV_CONTROL_TOKEN="…"  # do not put real secrets in shell history
+hookstride console
+
+# To start directly against production, explicitly select it
+hookstride --env production console
+```
+
+For safest handling, prefer `auth login` over typing tokens in shell commands.
+For interactive environment changes, the generic legacy
+`HOOKSTRIDE_CONTROL_TOKEN` is **never forwarded to another environment**.
+Use `auth login` separately after `set env production`, or provide a
+matching `HOOKSTRIDE_PRODUCTION_CONTROL_TOKEN` token. This prevents a dev
+token from accidentally being sent to the production API.
+
+The console requires a real interactive terminal and refuses `--json console`.
+For CI and scripting, use ordinary commands such as
+`hookstride --json events list` instead.
+
+## Output for scripts
+
+Pass `--json` **before** the command:
+
+```bash
+hookstride --json projects list | jq .
+hookstride --json events list --status failed | jq '.results'
+hookstride --env production --json billing history
+```
+
+The raw structured response is printed to stdout without terminal formatting. Network and HTTP errors go to stderr and cause a nonzero exit status.
+
+## Scope
+
+Version 0.2 includes interactive access to project, destination, incoming-source, delivery-stat, activity and billing **reads**. It does not yet create destinations, emit events, replay events, rotate credentials, or trigger payments. Those workflows require additional confirmation and integration tests before exposing them in a CLI. Server-side authorization, project scoping, and response redaction remain enforced by the Control API.
+
+Do not store passwords, signing secrets, private keys, or Paystack keys in Hookstride CLI configuration.

hookstride_cli-0.2.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hookstride-cli"
+version = "0.2.0"
+description = "Readable, project-scoped Hookstride Control API terminal client."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "Proprietary" }
+dependencies = [
+  "click>=8.1,<9",
+  "httpx>=0.28,<1",
+  "prompt-toolkit>=3.0.52,<4",
+  "rich>=14,<15",
+  "typer>=0.20,<1",
+]
+
+[project.scripts]
+hookstride = "hookstride_cli.main:main"
+
+[dependency-groups]
+dev = [
+  "pytest>=8.4,<10",
+  "ruff>=0.12,<1",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hookstride_cli"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+# Typer uses Option/Argument as intentional function defaults; long CLI lines
+# are formatted where practical without enforcing an arbitrary terminal width.
+ignore = ["B008", "E501"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

hookstride_cli-0.2.0/scripts/check.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# Local CLI validation, independent of GitHub Actions runner availability.
+set -euo pipefail
+
+cd "$(dirname "${BASH_SOURCE[0]}")/../.."
+
+echo "[1/5] Install/sync isolated CLI test dependencies"
+uv sync --project cli --group dev
+
+echo "[2/5] Static Python syntax check"
+uv run --project cli python -m compileall -q cli/src cli/tests
+
+echo "[3/5] Lint"
+uv run --project cli ruff check cli/src cli/tests
+
+echo "[4/5] Offline, mock-network tests (no live tokens)"
+uv run --project cli pytest -c cli/pyproject.toml -q cli/tests
+
+echo "[5/5] Command smoke tests"
+uv run --project cli hookstride --version
+uv run --project cli hookstride --help >/dev/null
+uv run --project cli hookstride console --help >/dev/null
+uv run --project cli hookstride --json config show
+
+echo "CLI checks passed. No live account or payment data was modified."

hookstride_cli-0.2.0/src/hookstride_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Hookstride developer CLI."""
+
+__version__ = "0.2.0"