command-gate 0.2.4__tar.gz

command_gate-0.2.4/.github/workflows/publish-pypi.yml

@@ -0,0 +1,32 @@
+name: "Publish to PyPI"
+
+"on":
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: "read"
+
+jobs:
+  publish:
+    name: "Build and publish"
+    runs-on: "ubuntu-latest"
+    environment:
+      name: "pypi"
+      url: "https://pypi.org/p/command-gate"
+    permissions:
+      id-token: "write"
+    steps:
+      - name: "Check out source"
+        uses: "actions/checkout@11d5960a326750d5838078e36cf38b85af677262" # v4.4.0
+      - name: "Set up Python"
+        uses: "actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065" # v5.6.0
+        with:
+          python-version: "3.12"
+      - name: "Install uv"
+        run: "python -m pip install 'uv>=0.8'"
+      - name: "Build sdist and wheel"
+        run: "uv build"
+      - name: "Publish to PyPI"
+        uses: "pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33" # v1.14.2

command_gate-0.2.4/.github/workflows/release.yml

@@ -0,0 +1,105 @@
+name: "Release binaries"
+
+"on":
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: "write"
+
+jobs:
+  build:
+    name: "Build ${{ matrix.asset }}"
+    runs-on: "${{ matrix.os }}"
+    permissions:
+      contents: "read"
+      id-token: "write"
+      attestations: "write"
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: "windows-latest"
+            asset: "cgate-windows-amd64.exe"
+          - os: "macos-latest"
+            asset: "cgate-macos-arm64"
+          - os: "ubuntu-latest"
+            asset: "cgate-linux-x86_64"
+    env:
+      UV_CACHE_DIR: "${{ github.workspace }}/.uv-cache"
+    steps:
+      - name: "Check out source"
+        uses: "actions/checkout@11d5960a326750d5838078e36cf38b85af677262" # v4.4.0
+      - name: "Set up Python"
+        uses: "actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065" # v5.6.0
+        with:
+          python-version: "3.12"
+      - name: "Cache uv packages"
+        uses: "actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830" # v4.3.0
+        with:
+          path: "${{ env.UV_CACHE_DIR }}"
+          key: >-
+            uv-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('pyproject.toml', 'uv.lock') }}
+          restore-keys: >-
+            uv-${{ runner.os }}-${{ runner.arch }}-
+      - name: "Install build tools"
+        run: "python -m pip install 'uv>=0.8' 'pyinstaller==6.*'"
+      - name: "Install project dependencies"
+        run: "uv sync --extra dev"
+      - name: "Build binary"
+        run: "uv run python scripts/build-binary.py"
+      - name: "Attest build provenance"
+        uses: "actions/attest-build-provenance@e8998f949152b193b063cb0ec769d69d929409be" # v2.4.0
+        with:
+          subject-path: "dist/${{ matrix.asset }}"
+      - name: "Upload binary artifact"
+        uses: "actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02" # v4.6.2
+        with:
+          name: "${{ matrix.asset }}"
+          path: "dist/${{ matrix.asset }}"
+          if-no-files-found: "error"
+      # Windows-only companion binary: performs the actual file swap/delete
+      # for `update apply` / `uninstall --binary` from a process that never
+      # shares an image name with cgate.exe, so there's nothing to
+      # disambiguate on Windows's process list (see src/cgate/helper/).
+      - name: "Build helper binary"
+        if: "matrix.os == 'windows-latest'"
+        run: >-
+          uv run python scripts/build-binary.py --name=cgate-helper
+          --entry=src/cgate/helper/__main__.py --minimal --windowed
+      - name: "Attest helper build provenance"
+        if: "matrix.os == 'windows-latest'"
+        uses: "actions/attest-build-provenance@e8998f949152b193b063cb0ec769d69d929409be" # v2.4.0
+        with:
+          subject-path: "dist/cgate-helper-windows-amd64.exe"
+      - name: "Upload helper binary artifact"
+        if: "matrix.os == 'windows-latest'"
+        uses: "actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02" # v4.6.2
+        with:
+          name: "cgate-helper-windows-amd64.exe"
+          path: "dist/cgate-helper-windows-amd64.exe"
+          if-no-files-found: "error"
+
+  release:
+    name: "Publish GitHub Release"
+    needs: "build"
+    runs-on: "ubuntu-latest"
+    steps:
+      - name: "Download binary artifacts"
+        uses: "actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093" # v4.3.0
+        with:
+          path: "."
+          merge-multiple: true
+      - name: "Create GitHub Release"
+        uses: "softprops/action-gh-release@3bb12739c298aeb8a4eeaf626c5b8d85266b0e65" # v2.6.2
+        with:
+          tag_name: "${{ github.ref_name }}"
+          name: "cgate ${{ github.ref_name }}"
+          body: "Auto-generated release for ${{ github.ref_name }}."
+          files: |
+            cgate-windows-amd64.exe
+            cgate-macos-arm64
+            cgate-linux-x86_64
+            cgate-helper-windows-amd64.exe
+          fail_on_unmatched_files: true

command_gate-0.2.4/.gitignore

@@ -0,0 +1,20 @@
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.ruff_cache/
+.basedpyright_cache/
+dist/
+build/
+*.egg-info/
+.idea/
+.vscode/
+.omo/
+.codegraph/
+
+# Generated by hatch-vcs at build time; mirrors the most recent git tag.
+src/cgate/_version.py
+
+# Generated by scripts/_ensure_repo.py; mirrors GITHUB_REPOSITORY / origin.
+src/cgate/_repo.py

command_gate-0.2.4/.python-version

@@ -0,0 +1 @@
+3.12

command_gate-0.2.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wanderlp
+
+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.

command_gate-0.2.4/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.5
+Name: command-gate
+Version: 0.2.4
+Summary: Middleware and CLI between AI assistants and managed servers so AI proposes commands, humans approve them, and every action is audited.
+Project-URL: Homepage, https://github.com/wanderlp/command-gate-for-ai-agents
+Project-URL: Repository, https://github.com/wanderlp/command-gate-for-ai-agents
+Project-URL: Issues, https://github.com/wanderlp/command-gate-for-ai-agents/issues
+Project-URL: Changelog, https://github.com/wanderlp/command-gate-for-ai-agents/releases
+Author: wanderlp
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,audit,cli,human-in-the-loop,mcp,ssh,winrm
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Systems Administration
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: keyring>=25.0
+Requires-Dist: mcp>=1.0
+Requires-Dist: packaging>=23.0
+Requires-Dist: paramiko>=3.0
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pywinrm>=0.4
+Requires-Dist: requests>=2.31
+Requires-Dist: rich>=13.0
+Requires-Dist: sigstore>=4.5.0
+Requires-Dist: textual>=8.2.8
+Requires-Dist: typer>=0.12
+Requires-Dist: typing-extensions>=4.12
+Provides-Extra: dev
+Requires-Dist: basedpyright>=1.13; extra == 'dev'
+Requires-Dist: hatch-vcs>=0.5; extra == 'dev'
+Requires-Dist: pyinstaller>=6.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# command-gate-for-ai-agents (`cgate`)
+
+Give your AI agents hands — safely.
+
+AI agents can now write and run real shell commands against real servers. That's
+powerful, and also the kind of thing that goes badly the first time an agent
+misunderstands what you asked for. `cgate` sits between the agent and your
+infrastructure: the agent proposes a command, a human decides whether it runs, and
+every proposal, decision, and result is recorded.
+
+You stop choosing between "the agent can't actually do anything" and "the agent can do
+anything, unsupervised."
+
+> **⚠️ Beta.** `cgate` is under active development. Expect rough edges, breaking
+> changes between releases, and incoming revisions as it matures — feedback and bug
+> reports are welcome.
+
+## Why teams use it
+
+- **Agents propose, humans decide.** Every command an AI agent wants to run on a
+  connected server lands in an approval queue first. Nothing executes without a human
+  saying yes.
+- **A full audit trail.** Every proposal, approval, rejection, and execution result is
+  recorded — who approved it, when, and what happened.
+- **Drops into the AI tools you already use.** Registers itself as an MCP server for
+  Claude Code, opencode, Cursor, and other MCP-compatible clients.
+- **One binary, nothing to configure.** Ships as a single executable per platform —
+  download it and run it, done.
+
+## Modes: PROPOSE and AUTO
+
+`cgate` ships in two modes, and you pick per server which ones can ever run
+unattended. The default is the safe one.
+
+**PROPOSE** (default): every command an AI agent calls lands in the watch queue. You
+press `y` or `n` per command. Nothing runs without you.
+
+**AUTO**: when the agent calls `propose_command`, it runs immediately **only if the
+target server is on your allow-list**. Servers are off by default — you opt them in
+explicitly. Two switches need to land in the "go" position before anything runs
+unattended: the global mode is AUTO *and* that specific server is opted in.
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│ cgate watch          MODE: AUTO ⚡ | 1 servers auto-allowed  │
+├─────────────────────────────────────────────────────────────┤
+│ [Queue]            [Servers]                                │
+│ ▶ "deploy v2"      dev-1   LNX [✓]                         │
+│                    stage-2 LNX [ ]                          │
+│                    prod-db WIN [ ]                          │
+├─────────────────────────────────────────────────────────────┤
+│ [y]approve [n]reject [a]approve batch [m]ode [h]istory ...  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+↑/↓ + Enter on the queue sidebar jumps straight to any pending batch — you're not
+forced to clear the queue in strict arrival order to get to the one you actually
+want to approve next.
+
+### Switching modes
+
+Press **`m`** in `cgate watch` to flip the global mode (one keystroke + `y` to
+confirm). Press **`s`** to open the server allow-list and toggle any connection on or
+off. Both modals need an explicit `y` or `Enter`; everything else cancels without
+writing. AI agents have no MCP tool that can change either setting — only your
+keystrokes can.
+
+### Why two switches?
+
+If you leave `MODE: AUTO` on by accident, the worst case is that nothing runs on
+servers that haven't been explicitly opted in. To actually run something
+unattended you must enable the mode **and** flip the per-server switch. Belt and
+suspenders, default-safe at every level.
+
+### A third switch: high-blast-radius commands never auto-run
+
+Even with both switches flipped, a command matching a known high-blast-radius
+pattern — a recursive force-delete, a raw disk write, deleting shadow copies or
+backups, disabling System Restore, and similar — always queues for a human. It
+shows a bold red `⚠ RISKY` warning in `cgate watch` (in **either** mode, so you
+notice it in PROPOSE too, not only when it changed what AUTO would have done),
+and the MCP response carries `effective_reason: "risky_command"` so the agent
+knows why. This is a regex-based heuristic, not a guarantee — it catches the
+common, obvious forms (see `src/cgate/risk.py`), not every possible obfuscation.
+Absence of the flag is not the same as "safe."
+
+### The audit trail still works
+
+Every command a batch ever queued shows an `⚙ auto` or `👤 <username>` badge next
+to it, so you always know whether a human or AUTO mode approved it — and once a
+batch resolves, it doesn't vanish: press **`h`** in `cgate watch` to browse every
+resolved batch, see the agent's stated `reason` for wanting the command, and view
+the full, untruncated result. Press **`/`** there to filter live against a batch's
+title, its commands, and their server aliases all at once -- `Esc` clears the
+filter first, then closes the screen on a second press.
+
+Need it outside the TUI — for a compliance report, or just to grep offline?
+
+```bash
+cgate history export                          # full audit trail as CSV, to stdout
+cgate history export --format json -o audit.json
+cgate history export --limit 100               # only the 100 most recently resolved batches
+```
+
+Human-only: this isn't exposed to AI agents over MCP. An agent that proposed a
+batch can already poll `check_status(batch_id)` for it at any time, resolved or
+not, so there's no reason to hand it a browse of everyone else's history too.
+
+Prefer raw SQL? The same data is still just a query away:
+
+```sql
+SELECT * FROM commands WHERE approved_by LIKE 'auto:%';
+```
+
+### What the AI sees (and what it can ask first)
+
+The MCP server exposes three read-only tools the AI can use to plan with full
+information, plus `propose_command` to act:
+
+- **`list_connections`** — every saved connection and its `auto_allowed` flag
+  (the AI knows up front which servers could auto-execute).
+- **`get_mode`** — the current global mode (`propose` or `auto`) and the list of
+  aliases opted into auto-execution. Read-only, safe to call any time.
+- **`check_status`** — what's pending in a given batch.
+
+With these, the AI never has to guess whether a command will auto-run or wait
+for you — it can call `get_mode` and `list_connections` first, plan accordingly,
+and only invoke `propose_command` when it knows what will happen.
+
+## Get started
+
+1. Download the binary for your platform from the
+   [latest release](https://github.com/wanderlp/command-gate-for-ai-agents/releases/latest).
+2. Run it (double-click it, or just `.\cgate-windows-amd64.exe` from the folder you
+   downloaded it to). On first run it installs itself into a per-user bin directory,
+   adds that directory to your `PATH`, and registers with any AI clients it finds —
+   no admin/sudo, no flags to remember.
+3. Open a new terminal and restart your AI client. Done.
+
+From there, `cgate watch` opens a live approval queue: agent proposals show up as they
+come in, you approve or reject with a keypress, and the result streams back to the
+agent.
+
+> First run on Windows or macOS may show a one-time "unrecognized publisher" warning —
+> these binaries aren't code-signed yet. See
+> [TECHNICAL.md](./TECHNICAL.md#first-run-warnings-binaries-are-not-code-signed) for
+> what to do about it.
+
+## Learn more
+
+Package-manager installs, architecture, development setup, and building from source
+live in [TECHNICAL.md](./TECHNICAL.md).
+
+## License
+
+[MIT](./LICENSE)

command_gate-0.2.4/README.md

@@ -0,0 +1,156 @@
+# command-gate-for-ai-agents (`cgate`)
+
+Give your AI agents hands — safely.
+
+AI agents can now write and run real shell commands against real servers. That's
+powerful, and also the kind of thing that goes badly the first time an agent
+misunderstands what you asked for. `cgate` sits between the agent and your
+infrastructure: the agent proposes a command, a human decides whether it runs, and
+every proposal, decision, and result is recorded.
+
+You stop choosing between "the agent can't actually do anything" and "the agent can do
+anything, unsupervised."
+
+> **⚠️ Beta.** `cgate` is under active development. Expect rough edges, breaking
+> changes between releases, and incoming revisions as it matures — feedback and bug
+> reports are welcome.
+
+## Why teams use it
+
+- **Agents propose, humans decide.** Every command an AI agent wants to run on a
+  connected server lands in an approval queue first. Nothing executes without a human
+  saying yes.
+- **A full audit trail.** Every proposal, approval, rejection, and execution result is
+  recorded — who approved it, when, and what happened.
+- **Drops into the AI tools you already use.** Registers itself as an MCP server for
+  Claude Code, opencode, Cursor, and other MCP-compatible clients.
+- **One binary, nothing to configure.** Ships as a single executable per platform —
+  download it and run it, done.
+
+## Modes: PROPOSE and AUTO
+
+`cgate` ships in two modes, and you pick per server which ones can ever run
+unattended. The default is the safe one.
+
+**PROPOSE** (default): every command an AI agent calls lands in the watch queue. You
+press `y` or `n` per command. Nothing runs without you.
+
+**AUTO**: when the agent calls `propose_command`, it runs immediately **only if the
+target server is on your allow-list**. Servers are off by default — you opt them in
+explicitly. Two switches need to land in the "go" position before anything runs
+unattended: the global mode is AUTO *and* that specific server is opted in.
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│ cgate watch          MODE: AUTO ⚡ | 1 servers auto-allowed  │
+├─────────────────────────────────────────────────────────────┤
+│ [Queue]            [Servers]                                │
+│ ▶ "deploy v2"      dev-1   LNX [✓]                         │
+│                    stage-2 LNX [ ]                          │
+│                    prod-db WIN [ ]                          │
+├─────────────────────────────────────────────────────────────┤
+│ [y]approve [n]reject [a]approve batch [m]ode [h]istory ...  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+↑/↓ + Enter on the queue sidebar jumps straight to any pending batch — you're not
+forced to clear the queue in strict arrival order to get to the one you actually
+want to approve next.
+
+### Switching modes
+
+Press **`m`** in `cgate watch` to flip the global mode (one keystroke + `y` to
+confirm). Press **`s`** to open the server allow-list and toggle any connection on or
+off. Both modals need an explicit `y` or `Enter`; everything else cancels without
+writing. AI agents have no MCP tool that can change either setting — only your
+keystrokes can.
+
+### Why two switches?
+
+If you leave `MODE: AUTO` on by accident, the worst case is that nothing runs on
+servers that haven't been explicitly opted in. To actually run something
+unattended you must enable the mode **and** flip the per-server switch. Belt and
+suspenders, default-safe at every level.
+
+### A third switch: high-blast-radius commands never auto-run
+
+Even with both switches flipped, a command matching a known high-blast-radius
+pattern — a recursive force-delete, a raw disk write, deleting shadow copies or
+backups, disabling System Restore, and similar — always queues for a human. It
+shows a bold red `⚠ RISKY` warning in `cgate watch` (in **either** mode, so you
+notice it in PROPOSE too, not only when it changed what AUTO would have done),
+and the MCP response carries `effective_reason: "risky_command"` so the agent
+knows why. This is a regex-based heuristic, not a guarantee — it catches the
+common, obvious forms (see `src/cgate/risk.py`), not every possible obfuscation.
+Absence of the flag is not the same as "safe."
+
+### The audit trail still works
+
+Every command a batch ever queued shows an `⚙ auto` or `👤 <username>` badge next
+to it, so you always know whether a human or AUTO mode approved it — and once a
+batch resolves, it doesn't vanish: press **`h`** in `cgate watch` to browse every
+resolved batch, see the agent's stated `reason` for wanting the command, and view
+the full, untruncated result. Press **`/`** there to filter live against a batch's
+title, its commands, and their server aliases all at once -- `Esc` clears the
+filter first, then closes the screen on a second press.
+
+Need it outside the TUI — for a compliance report, or just to grep offline?
+
+```bash
+cgate history export                          # full audit trail as CSV, to stdout
+cgate history export --format json -o audit.json
+cgate history export --limit 100               # only the 100 most recently resolved batches
+```
+
+Human-only: this isn't exposed to AI agents over MCP. An agent that proposed a
+batch can already poll `check_status(batch_id)` for it at any time, resolved or
+not, so there's no reason to hand it a browse of everyone else's history too.
+
+Prefer raw SQL? The same data is still just a query away:
+
+```sql
+SELECT * FROM commands WHERE approved_by LIKE 'auto:%';
+```
+
+### What the AI sees (and what it can ask first)
+
+The MCP server exposes three read-only tools the AI can use to plan with full
+information, plus `propose_command` to act:
+
+- **`list_connections`** — every saved connection and its `auto_allowed` flag
+  (the AI knows up front which servers could auto-execute).
+- **`get_mode`** — the current global mode (`propose` or `auto`) and the list of
+  aliases opted into auto-execution. Read-only, safe to call any time.
+- **`check_status`** — what's pending in a given batch.
+
+With these, the AI never has to guess whether a command will auto-run or wait
+for you — it can call `get_mode` and `list_connections` first, plan accordingly,
+and only invoke `propose_command` when it knows what will happen.
+
+## Get started
+
+1. Download the binary for your platform from the
+   [latest release](https://github.com/wanderlp/command-gate-for-ai-agents/releases/latest).
+2. Run it (double-click it, or just `.\cgate-windows-amd64.exe` from the folder you
+   downloaded it to). On first run it installs itself into a per-user bin directory,
+   adds that directory to your `PATH`, and registers with any AI clients it finds —
+   no admin/sudo, no flags to remember.
+3. Open a new terminal and restart your AI client. Done.
+
+From there, `cgate watch` opens a live approval queue: agent proposals show up as they
+come in, you approve or reject with a keypress, and the result streams back to the
+agent.
+
+> First run on Windows or macOS may show a one-time "unrecognized publisher" warning —
+> these binaries aren't code-signed yet. See
+> [TECHNICAL.md](./TECHNICAL.md#first-run-warnings-binaries-are-not-code-signed) for
+> what to do about it.
+
+## Learn more
+
+Package-manager installs, architecture, development setup, and building from source
+live in [TECHNICAL.md](./TECHNICAL.md).
+
+## License
+
+[MIT](./LICENSE)