bot-cmder 0.2.0__tar.gz

bot_cmder-0.2.0/.dockerignore

@@ -0,0 +1,69 @@
+# Keep the build context small + deterministic — only the files that
+# the wheel build actually needs. Everything else is either:
+#   - re-derivable (.venv, dist, __pycache__)
+#   - state that doesn't belong in an image (var, .env)
+#   - irrelevant to the runtime (tests, docs, CI configs)
+#   - agent-local (.claude)
+
+# Version control + IDE state
+.git
+.gitignore
+.gitleaks.toml
+.gitattributes
+.editorconfig
+.vscode
+.idea
+
+# Agent worktrees, plans, ephemeral state
+.claude
+
+# Python build / test artifacts
+.venv
+.pytest_cache
+.ruff_cache
+.mypy_cache
+.coverage
+htmlcov
+**/__pycache__
+**/*.pyc
+**/*.pyo
+
+# Local build outputs (wheels are rebuilt inside the builder stage)
+dist
+build
+*.egg-info
+
+# Repo-local bot state (never ship audit logs, totp secrets, etc.)
+var
+runbooks
+
+# Operator config — must be mounted at runtime, never baked in
+.env
+.env.example
+.env.local
+config/app.yaml
+config/app.yaml.local
+
+# Tests + dev-only files don't run inside the image
+tests
+.pre-commit-config.yaml
+
+# Docs, examples, scripts that don't ship in the wheel
+docs
+scripts/tunnel*.sh
+scripts/show_env_settings.py
+scripts/hook_status.py
+
+# CI configuration — building from source doesn't need these inside
+# the container, GitHub Actions reads them from the repo directly
+.github
+
+# OS / editor cruft
+.DS_Store
+Thumbs.db
+*.swp
+*.swo
+*~
+
+# Justfile — only needed for source contributors, not in the image
+Justfile

bot_cmder-0.2.0/.env.example

@@ -0,0 +1,161 @@
+# Telegram bot token from @BotFather.
+TELEGRAM_TOKEN=
+
+# Optional: any long random string. When set, the bot rejects webhook
+# requests whose `X-Telegram-Bot-Api-Secret-Token` header does not match.
+# Set the same value when calling setWebhook (see Justfile).
+TELEGRAM_WEBHOOK_SECRET=
+
+# Phase 6a — ingestion mode.
+#   - "webhook" (default): bot exposes POST /webhooks/telegram and
+#     Telegram POSTs each update there. Requires public HTTPS URL
+#     (set TELEGRAM_HOOK_URL below or use `just tunnel-ngrok`).
+#   - "polling": bot dials OUT to api.telegram.org and long-polls for
+#     updates. NO public URL, NO tunnel needed — ideal for home labs
+#     / NAT / corp egress restrictions. The two modes are mutually
+#     exclusive in Telegram's API; the daemon auto-deletes any
+#     registered webhook at startup so flipping the mode Just Works.
+TELEGRAM_MODE=webhook
+
+# Polling-mode tuning (ignored unless TELEGRAM_MODE=polling).
+# Telegram caps the long-poll wait at 50s; 25s is a sweet spot —
+# fewer requests than short polling, but stays under most middleboxes'
+# silent-drop window.
+TELEGRAM_POLLING_TIMEOUT_S=25
+# When flipping to polling, drop any updates Telegram queued while a
+# webhook was active. Useful during dev mode flapping (don't replay
+# yesterday's tests). Leave false in prod so a brief webhook outage
+# doesn't lose updates.
+TELEGRAM_POLLING_DROP_PENDING=false
+
+# Public HTTPS URL where Telegram will deliver updates. Used by
+# `just set-telegram-bot-webhook` only — not read by the running app.
+# Auto-overwritten by `just tunnel` and `just tunnel-ngrok`.
+# Ignored entirely in TELEGRAM_MODE=polling.
+TELEGRAM_HOOK_URL=
+
+# Reserved ngrok static domain for `just tunnel-ngrok`. Get a free
+# one at https://dashboard.ngrok.com/domains. Stable across ngrok
+# restarts, so DNS never has propagation lag (unlike trycloudflare).
+#
+# IMPORTANT: just the bare hostname — no `https://` prefix, no path
+# suffix. The tunnel script adds those itself; pasting the full URL
+# corrupts TELEGRAM_HOOK_URL and ngrok rejects with ERR_NGROK_9038.
+#   ✓  NGROK_DOMAIN=your-reserved-domain.ngrok-free.dev
+#   ✗  NGROK_DOMAIN=https://your-reserved-domain.ngrok-free.dev/webhooks/telegram
+NGROK_DOMAIN=
+
+# Path to the app YAML config (users, ACL, healthcheck targets, ...).
+APP_CONFIG_PATH=./config/app.yaml
+
+# Optional override for the audit log path. Falls back to the path set
+# in app.yaml under `audit.path`.
+# AUDIT_PATH=./var/audit.jsonl
+
+# Optional uvicorn bind overrides. Defaults: 127.0.0.1:47823 with no
+# autoreload. Port 47823 is intentionally uncommon to avoid clashing
+# with other dev services on 8000 / 8080.
+# BIND_HOST=127.0.0.1
+# BIND_PORT=47823
+# RELOAD=1
+
+# Phase 2 — Fernet symmetric key used to encrypt TOTP secrets at rest
+# in the SQLite store. REQUIRED to enable the OTP gate; without it
+# privileged commands (/kubectl, /runbook run, anything with
+# Risk.PRIVILEGED) cannot be authorized and refuse to run.
+#
+# Generate one with:
+#   python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+#
+# WARNING: rotating this key invalidates every existing TOTP enrollment.
+# All users will need to re-run `python -m bot_cmder.cli enroll-totp`.
+BOT_CMDER_MASTER_KEY=
+
+# Phase 4 — Discord adapter. All three are required for the adapter
+# to mount /webhooks/discord; without them the bot still runs but
+# Discord is silently disabled (logged at WARNING during startup).
+#
+# DISCORD_PUBLIC_KEY: Ed25519 verify key (hex). Discord application
+#   "General Information" → "Public Key". Used to verify every
+#   incoming interaction; Discord refuses to onboard endpoints that
+#   don't enforce signing, so this is non-negotiable.
+DISCORD_PUBLIC_KEY=
+# DISCORD_BOT_TOKEN: bot token from "Bot" page. Used to PATCH
+#   deferred replies via Discord's webhook API and to PUT the slash
+#   command schema (scripts/register_discord_commands.py).
+DISCORD_BOT_TOKEN=
+# DISCORD_APPLICATION_ID: numeric application ID (in the URL of the
+#   application page). Goes into the follow-up @original PATCH path.
+DISCORD_APPLICATION_ID=
+
+# DISCORD_GUILD_ID: optional. Read ONLY by scripts/register_discord_commands.py
+#   — the running bot never touches this value. When set, `just register-discord`
+#   pushes the slash command schema to that one server (instant propagation,
+#   recommended for dev). When unset, registration goes global (~1h propagation,
+#   visible in every server the bot is in + DMs, recommended for prod).
+#   Override per-call with `just register-discord --guild=<id>` or force a
+#   global push with `just register-discord --global`.
+#
+# Get the ID: Discord client → Settings → Advanced → Developer Mode (on),
+# then right-click your server icon → Copy Server ID.
+DISCORD_GUILD_ID=
+
+# Phase 6c — ingestion mode for the Discord adapter.
+#   - "interactions" (default): bot exposes POST /webhooks/discord and
+#     Discord POSTs slash commands there. Requires public HTTPS URL +
+#     DISCORD_PUBLIC_KEY for Ed25519 verification. This is Phase 4
+#     behavior, preserved as the default.
+#   - "gateway": bot opens a WebSocket OUT to Discord and chat events
+#     arrive over that. NO public URL needed; ideal for home labs / NAT.
+#     **Slash commands DON'T arrive over the Gateway** (Discord
+#     platform limitation) — UX shifts to `@bot cmd args` in guild
+#     channels or plain `cmd args` in DMs. Needs the MESSAGE_CONTENT
+#     privileged intent enabled in the dev portal (Bot → Privileged
+#     Gateway Intents → Message Content Intent).
+# Anything other than "interactions" / "gateway" fails fast at startup.
+DISCORD_MODE=interactions
+
+# Phase 5/6b — Slack adapter. Two ingestion modes (mutually exclusive
+# in Slack's app config — when Socket Mode is toggled on, the Events
+# API URL field greys out):
+#   - "events" (default): /webhooks/slack receives Slack POSTs.
+#     Needs SLACK_SIGNING_SECRET. Requires public HTTPS URL.
+#   - "socket": bot opens WebSocket OUT to Slack. Needs SLACK_APP_TOKEN.
+#     NO public URL needed; ideal for home labs / NAT.
+# Without the relevant secret(s) the bot still runs but Slack is
+# silently disabled (logged at WARNING during startup).
+SLACK_MODE=events
+
+# SLACK_SIGNING_SECRET (events mode only): 32-char hex string from
+#   your Slack app's "Basic Information" → "App Credentials" →
+#   "Signing Secret". Used to verify every incoming slash command via
+#   HMAC-SHA256(`v0:<ts>:<body>`). Slack rejects endpoints that accept
+#   unsigned payloads.
+SLACK_SIGNING_SECRET=
+
+# SLACK_APP_TOKEN (socket mode only): app-level token from "Basic
+#   Information" → "App-Level Tokens" → Generate (scope:
+#   `connections:write`). Distinct from SLACK_BOT_TOKEN — this one
+#   authorizes opening the Socket Mode WebSocket connection.
+SLACK_APP_TOKEN=
+
+# SLACK_BOT_TOKEN: bot user OAuth token from "OAuth & Permissions"
+#   page (xoxb-...). Optional for both modes today; reserved for
+#   future chat.postMessage-based replies (Block Kit etc.).
+SLACK_BOT_TOKEN=
+
+# Read ONLY by scripts/register_slack_commands.py (the running bot
+# never touches it — Slack tells the bot where the request came from
+# per-call). Public HTTPS URL Slack should POST slash commands to.
+# Bare hostname OK — the script appends /webhooks/slack:
+#   ✓  SLACK_REQUEST_URL=my-tunnel.ngrok-free.dev
+#   ✓  SLACK_REQUEST_URL=https://my-tunnel.ngrok-free.dev
+#   ✓  SLACK_REQUEST_URL=https://my-tunnel.ngrok-free.dev/webhooks/slack
+# When unset, falls back to NGROK_DOMAIN. When that's also unset,
+# `just register-slack` errors out so a placeholder URL never lands
+# in the Slack manifest.
+SLACK_REQUEST_URL=
+
+# Reply visibility (ephemeral / in_channel / by_risk + per-command
+# overrides) is configured in `config/app.yaml` under `slack:`, NOT
+# here — it's tunable behavior, not a secret.

bot_cmder-0.2.0/.github/dependabot.yml

@@ -0,0 +1,41 @@
+# Keeps deps and Action versions fresh by opening one PR per upgrade.
+# Each PR runs through CI like any other change, so you only have to
+# look at green/red instead of remembering when you last ran
+# `uv sync --upgrade`.
+#
+# Cadence rationale:
+#   - "weekly" not "daily": daily floods the inbox; weekly batches
+#     enough churn to be worth reviewing without going stale.
+#   - Caps at 5 open PRs per ecosystem so a bad upstream week
+#     (e.g. 20 actions get patches at once) doesn't bury everything.
+
+version: 2
+
+updates:
+  # GitHub Actions used in .github/workflows/*.yml — pins like
+  # actions/checkout@v4 will get bumped to v5 etc.
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: "ci"
+      include: "scope"
+
+  # Python deps tracked via pyproject.toml + uv.lock. Dependabot's
+  # `pip` ecosystem reads pyproject and updates uv.lock alongside it
+  # (it has uv support since late 2024).
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    # Group all dev-only updates into ONE PR per week — they rarely
+    # need individual scrutiny (it's just lint/test tooling).
+    groups:
+      dev-tools:
+        dependency-type: "development"
+    commit-message:
+      prefix: "deps"
+      include: "scope"

bot_cmder-0.2.0/.github/workflows/beta.yml

@@ -0,0 +1,100 @@
+# Test PyPI publish — issue #20 PR-B.
+#
+# Triggered by pushing to the `beta` branch. Mirrors the
+# `zondatw/remote-cmder` workflow pattern (branch-based triggers
+# instead of tag-based) so the publish flow feels familiar across
+# Zonda's repos:
+#
+#   git checkout beta
+#   git merge main          # forward whatever was just verified
+#   git push                # ← this is the trigger
+#
+# After the workflow goes green, eyeball https://test.pypi.org/project/bot-cmder/
+# in a browser. If the page renders the README correctly, license
+# shows MIT, and `pip install --index-url https://test.pypi.org/simple/
+# --extra-index-url https://pypi.org/simple/ bot-cmder` works in a
+# fresh venv → safe to forward to the `release` branch.
+#
+# Auth: PyPI Trusted Publishing (OIDC). No long-lived `TWINE_PASSWORD`
+# in repo secrets — GitHub mints a short-lived token at publish time
+# and PyPI validates it against the pending publisher configured on
+# the test.pypi.org side. See docs/release.md for the one-time setup.
+#
+# Why a separate `beta` branch and not a `--repository test.pypi.org`
+# flag on a workflow_dispatch: matches the repo-mate pattern, and a
+# dedicated branch's HEAD makes "what's currently on test.pypi.org?"
+# answerable with `git log beta`.
+
+name: beta
+
+on:
+  push:
+    branches: [beta]
+
+# Don't cancel an in-flight publish if a second push lands on beta —
+# that would leave test.pypi.org in an inconsistent state. Each push
+# waits for the previous to finish.
+concurrency:
+  group: beta-publish
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: build wheel + sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install Python
+        run: uv python install 3.12
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Verify wheel ships expected data files
+        run: |
+          set -euo pipefail
+          WHEEL=$(ls dist/*.whl)
+          echo "Inspecting $WHEEL"
+          unzip -l "$WHEEL" | grep -q 'bot_cmder/data/app.yaml.example' || (
+            echo "ERROR: bot_cmder/data/app.yaml.example missing from wheel"
+            exit 1
+          )
+          unzip -l "$WHEEL" | grep -q 'bot_cmder/auth/migrations/0001_initial.sql' || (
+            echo "ERROR: bot_cmder/auth/migrations/0001_initial.sql missing from wheel"
+            exit 1
+          )
+          echo "OK — wheel contents verified"
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+          retention-days: 7
+
+  publish-test:
+    name: publish to test.pypi.org
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: release-test
+      url: https://test.pypi.org/project/bot-cmder/
+    permissions:
+      # Required for PyPI Trusted Publishing — GitHub mints a short-
+      # lived OIDC token that test.pypi.org exchanges for an upload
+      # credential. No long-lived API token in repo secrets.
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to Test PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

bot_cmder-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,200 @@
+# GitHub Actions CI — runs the full test suite + lint on every push to
+# main and on every PR. Mirrors what `just test` and `pre-commit run
+# --all-files` do locally so a green CI badge actually means something.
+#
+# Why two jobs (test + lint) instead of one:
+#   - Different inputs change them independently — a doc typo touches
+#     lint only, a handler change touches test only. Splitting lets
+#     you see at a glance which side broke.
+#   - They can run in parallel (faster red-line on broken PRs).
+#
+# Why matrix Python 3.10 and 3.12 (skipping 3.11):
+#   - 3.10 is the floor declared in pyproject.toml `requires-python`
+#     and `tool.ruff.target-version`. If we don't test it, "supports
+#     3.10" is a lie.
+#   - 3.12 is the latest widely-deployed stable. Catches accidental
+#     use of removed-in-3.12 APIs (e.g. distutils, asyncio.coroutine).
+#   - Skipping 3.11 halves matrix runtime; if either neighbor passes,
+#     3.11 almost always does too.
+
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# Cancel a previous in-flight run for the same ref when a new commit
+# lands on a PR — saves CI minutes and gets the latest result faster.
+# Pushes to main are NOT cancelled (the `|| github.run_id` makes each
+# main push its own group).
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}-${{ github.event_name == 'push' && github.run_id || '' }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  test:
+    name: pytest (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.12"]
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@v6
+
+      - name: Install uv (with cache)
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Pin Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Sync dependencies (locked)
+        # --frozen: refuse to update uv.lock; CI must use the exact
+        # versions a developer committed, otherwise "works on my
+        # machine" creeps back in via silent upgrades.
+        run: uv sync --frozen --python ${{ matrix.python-version }}
+
+      - name: Run pytest
+        run: uv run --python ${{ matrix.python-version }} pytest
+
+  lint:
+    name: pre-commit
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@v6
+
+      - name: Set up Python 3.12
+        # Single Python is enough — black / ruff / codespell are all
+        # version-agnostic for our codebase.
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Run pre-commit hooks
+        # The official action handles caching of hook envs (which
+        # otherwise re-clone black + ruff repos on every run).
+        uses: pre-commit/action@v3.0.1
+
+  # Issue #20 — wheel-build smoke test runs the same build steps the
+  # release workflows (.github/workflows/{beta,release}.yml) do, but
+  # on every PR. Catches packaging regressions at PR time instead of
+  # at release time. Examples of what would have shipped broken
+  # without this gate:
+  #   - someone deletes bot_cmder/data/__init__.py → app.yaml.example
+  #     stops shipping in the wheel → `bot-cmder init` 500s on every
+  #     install
+  #   - a refactor breaks the [project.scripts] entry → `bot-cmder`
+  #     console script absent after `pip install`
+  #   - import error in cli/__init__.py → `bot-cmder --help` raises
+  #     before printing usage
+  # Each of those is silent in the test suite (which uses the editable
+  # install) but breaks the wheel.
+  wheel-build:
+    name: wheel build smoke test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@v6
+
+      - name: Install uv (with cache)
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Pin Python 3.12
+        run: uv python install 3.12
+
+      - name: Build wheel + sdist
+        run: uv build
+
+      - name: Verify wheel ships expected data files
+        # Same checks the release workflows do — keep in sync. The
+        # set is small enough to inline; if it grows, factor into a
+        # shared bash script under scripts/.
+        run: |
+          set -euo pipefail
+          WHEEL=$(ls dist/*.whl)
+          echo "Inspecting $WHEEL"
+          unzip -l "$WHEEL" | grep -q 'bot_cmder/data/app.yaml.example' || (
+            echo "ERROR: bot_cmder/data/app.yaml.example missing from wheel"
+            exit 1
+          )
+          unzip -l "$WHEEL" | grep -q 'bot_cmder/auth/migrations/0001_initial.sql' || (
+            echo "ERROR: bot_cmder/auth/migrations/0001_initial.sql missing from wheel"
+            exit 1
+          )
+          echo "OK — wheel data files present"
+
+      - name: Smoke install + run --version
+        # Fresh venv install of the wheel exercises:
+        #   - [project.scripts] entry point lands `bot-cmder` on PATH
+        #   - lazy imports in cli/__init__.py + subcommands resolve
+        #   - bot_cmder.__version__ is accessible at runtime
+        # If `bot-cmder --version` exits non-zero or prints empty, fail.
+        run: |
+          set -euo pipefail
+          python3 -m venv /tmp/smoke
+          /tmp/smoke/bin/pip install --quiet dist/*.whl
+          ver=$(/tmp/smoke/bin/bot-cmder --version)
+          echo "Got: $ver"
+          echo "$ver" | grep -qE '^bot-cmder [0-9]+\.[0-9]+\.[0-9]+' || (
+            echo "ERROR: --version output didn't match 'bot-cmder X.Y.Z'"
+            exit 1
+          )
+          # Also exercise the no-args case to catch a regression in
+          # argparse setup (e.g. missing required=True on subparsers
+          # would silently no-op instead of printing usage + exiting 2).
+          /tmp/smoke/bin/bot-cmder >/dev/null 2>&1 && (
+            echo "ERROR: bot-cmder with no args should exit non-zero"
+            exit 1
+          ) || echo "OK — no-args path exits non-zero as expected"
+
+  # Phase 7 — secret-scan is its own job (not a step in lint) because
+  # it's a security gate, not a style gate. When it fails on a PR the
+  # status check name "secret-scan" is unambiguous about what broke,
+  # and the red badge is visually distinct from "pre-commit failed
+  # because black wanted to reformat". Runs in parallel with lint
+  # and test so it doesn't add to total CI wall-clock time.
+  secret-scan:
+    name: secret-scan
+    runs-on: ubuntu-latest
+    # gitleaks-action calls /repos/.../pulls/N/commits to enumerate
+    # the PR's commits. The default GITHUB_TOKEN doesn't grant that
+    # scope (`Resource not accessible by integration` 403 otherwise).
+    # Read-only `pull-requests: read` is the minimum that satisfies
+    # the API call without giving the action write access to anything.
+    permissions:
+      contents: read
+      pull-requests: read
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@v6
+        with:
+          # gitleaks needs the FULL history to scan every commit in
+          # the PR (not just the merge tip). Default checkout is a
+          # shallow clone with depth=1; override to fetch everything.
+          fetch-depth: 0
+
+      - name: Run gitleaks
+        # Pinned action version + the same gitleaks binary version
+        # we run locally (.pre-commit-config.yaml). Config is
+        # auto-discovered from .gitleaks.toml at the repo root.
+        uses: gitleaks/gitleaks-action@v2
+        env:
+          # Required by gitleaks-action@v2 for scanning pull
+          # requests (announced as a breaking change in their
+          # README). The auto-provisioned per-run token is
+          # sufficient — no PAT needed.
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # Quiet the marketing pop-up about gitleaks-pro that the
+          # action would otherwise print on every run for OSS repos.
+          GITLEAKS_NOTIFY_USER_LIST: ""
+          GITLEAKS_ENABLE_UPLOAD_ARTIFACT: "false"
+          GITLEAKS_ENABLE_SUMMARY: "true"