merge-gateway 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. merge_gateway-0.1.0/.github/CODEOWNERS +1 -0
  2. merge_gateway-0.1.0/.github/dependabot.yml +9 -0
  3. merge_gateway-0.1.0/.github/pull_request_template.md +18 -0
  4. merge_gateway-0.1.0/.github/workflows/ci.yml +36 -0
  5. merge_gateway-0.1.0/.github/workflows/publish.yml +23 -0
  6. merge_gateway-0.1.0/.gitignore +19 -0
  7. merge_gateway-0.1.0/.python-version +1 -0
  8. merge_gateway-0.1.0/AGENTS.md +95 -0
  9. merge_gateway-0.1.0/CLAUDE.md +1 -0
  10. merge_gateway-0.1.0/Makefile +28 -0
  11. merge_gateway-0.1.0/PKG-INFO +84 -0
  12. merge_gateway-0.1.0/README.md +61 -0
  13. merge_gateway-0.1.0/mgw/__init__.py +3 -0
  14. merge_gateway-0.1.0/mgw/api.py +322 -0
  15. merge_gateway-0.1.0/mgw/auth/__init__.py +1 -0
  16. merge_gateway-0.1.0/mgw/auth/flow.py +77 -0
  17. merge_gateway-0.1.0/mgw/auth/login.py +65 -0
  18. merge_gateway-0.1.0/mgw/auth/loopback.py +110 -0
  19. merge_gateway-0.1.0/mgw/auth/pkce.py +23 -0
  20. merge_gateway-0.1.0/mgw/auth/store.py +130 -0
  21. merge_gateway-0.1.0/mgw/cli.py +35 -0
  22. merge_gateway-0.1.0/mgw/commands/__init__.py +1 -0
  23. merge_gateway-0.1.0/mgw/commands/agent.py +261 -0
  24. merge_gateway-0.1.0/mgw/commands/doctor.py +88 -0
  25. merge_gateway-0.1.0/mgw/commands/keys.py +90 -0
  26. merge_gateway-0.1.0/mgw/commands/login.py +24 -0
  27. merge_gateway-0.1.0/mgw/commands/logout.py +24 -0
  28. merge_gateway-0.1.0/mgw/commands/setup.py +95 -0
  29. merge_gateway-0.1.0/mgw/config.py +60 -0
  30. merge_gateway-0.1.0/mgw/harness/__init__.py +15 -0
  31. merge_gateway-0.1.0/mgw/harness/base.py +60 -0
  32. merge_gateway-0.1.0/mgw/harness/claude_code.py +65 -0
  33. merge_gateway-0.1.0/mgw/harness/codex.py +68 -0
  34. merge_gateway-0.1.0/mgw/provision.py +90 -0
  35. merge_gateway-0.1.0/pyproject.toml +54 -0
  36. merge_gateway-0.1.0/tests/__init__.py +0 -0
  37. merge_gateway-0.1.0/tests/conftest.py +27 -0
  38. merge_gateway-0.1.0/tests/test_agent_command.py +308 -0
  39. merge_gateway-0.1.0/tests/test_api.py +159 -0
  40. merge_gateway-0.1.0/tests/test_api_agent.py +115 -0
  41. merge_gateway-0.1.0/tests/test_auth_flow.py +101 -0
  42. merge_gateway-0.1.0/tests/test_auth_login.py +88 -0
  43. merge_gateway-0.1.0/tests/test_auth_pkce.py +38 -0
  44. merge_gateway-0.1.0/tests/test_auth_store.py +76 -0
  45. merge_gateway-0.1.0/tests/test_cli.py +21 -0
  46. merge_gateway-0.1.0/tests/test_config.py +49 -0
  47. merge_gateway-0.1.0/tests/test_doctor.py +149 -0
  48. merge_gateway-0.1.0/tests/test_harness_claude_code.py +124 -0
  49. merge_gateway-0.1.0/tests/test_harness_codex.py +105 -0
  50. merge_gateway-0.1.0/tests/test_keys.py +103 -0
  51. merge_gateway-0.1.0/tests/test_login_command.py +36 -0
  52. merge_gateway-0.1.0/tests/test_logout.py +29 -0
  53. merge_gateway-0.1.0/tests/test_provision.py +122 -0
  54. merge_gateway-0.1.0/tests/test_setup.py +128 -0
  55. merge_gateway-0.1.0/uv.lock +285 -0
@@ -0,0 +1 @@
1
+ * @merge-api/gateway-engineering
@@ -0,0 +1,9 @@
1
+ # Python deps (uv.lock) are not covered here: Dependabot's classic
2
+ # package-ecosystem list doesn't include "uv", and uv's own docs point uv-lock
3
+ # users to Renovate. Bump Python deps with `uv lock --upgrade` (or add Renovate).
4
+ version: 2
5
+ updates:
6
+ - package-ecosystem: "github-actions"
7
+ directory: "/"
8
+ schedule:
9
+ interval: "weekly"
@@ -0,0 +1,18 @@
1
+ ## What
2
+
3
+ <!-- One or two sentences: what this change does. -->
4
+
5
+ ## Why
6
+
7
+ <!-- The motivation / linked issue. -->
8
+
9
+ ## Testing
10
+
11
+ <!-- How you verified it. New/updated tests? `uv run pytest`? Manual steps? -->
12
+
13
+ ## Checklist
14
+
15
+ - [ ] `uv run ruff format` and `uv run ruff check` pass
16
+ - [ ] `uv run pytest` passes
17
+ - [ ] New behavior is covered by tests (TDD)
18
+ - [ ] No secrets in code, logs, or fixtures
@@ -0,0 +1,36 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+
8
+ concurrency:
9
+ group: ci-${{ github.ref }}
10
+ cancel-in-progress: true
11
+
12
+ jobs:
13
+ lint:
14
+ runs-on: blacksmith-4vcpu-ubuntu-2404
15
+ steps:
16
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
17
+ - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
18
+ with:
19
+ enable-cache: true
20
+ - run: uv sync --locked
21
+ - run: uv run ruff check .
22
+ - run: uv run ruff format --check .
23
+
24
+ test:
25
+ runs-on: blacksmith-4vcpu-ubuntu-2404
26
+ strategy:
27
+ matrix:
28
+ python-version: ["3.10", "3.11", "3.12", "3.13"]
29
+ steps:
30
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
31
+ - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
32
+ with:
33
+ enable-cache: true
34
+ python-version: ${{ matrix.python-version }}
35
+ - run: uv sync --locked
36
+ - run: uv run pytest -q
@@ -0,0 +1,23 @@
1
+ name: Publish to PyPI
2
+
3
+ # Fires on a published GitHub Release, not on merge: cut a release to ship.
4
+ on:
5
+ release:
6
+ types: [published]
7
+
8
+ jobs:
9
+ publish:
10
+ runs-on: ubuntu-latest
11
+ environment: pypi
12
+ permissions:
13
+ contents: read
14
+ id-token: write
15
+ steps:
16
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
17
+ - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
18
+ with:
19
+ enable-cache: true
20
+ - run: uv sync --locked
21
+ - run: uv run pytest -q
22
+ - run: uv build
23
+ - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
@@ -0,0 +1,19 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *.egg-info/
5
+ .eggs/
6
+ build/
7
+ dist/
8
+
9
+ # Virtualenv / uv
10
+ .venv/
11
+
12
+ # Test / coverage
13
+ .pytest_cache/
14
+ .ruff_cache/
15
+ .coverage
16
+ htmlcov/
17
+
18
+ # OS / editor
19
+ .DS_Store
@@ -0,0 +1 @@
1
+ 3.12
@@ -0,0 +1,95 @@
1
+ # AGENTS.md
2
+
3
+ Guidance for AI coding agents (Claude Code, Codex, and others) working in this
4
+ repository. `CLAUDE.md` is a symlink to this file, so every tool reads the same
5
+ source.
6
+
7
+ ## Project overview
8
+
9
+ `mgw` is the Merge Gateway CLI. It gives developers a seamless way to route
10
+ their existing coding agents (Claude Code, Codex) through Merge Gateway:
11
+
12
+ 1. `mgw login` — browser-based sign-in to the control plane using a
13
+ loopback + PKCE OAuth flow; stores a short-lived credential locally.
14
+ 2. `mgw setup <harness>` — mints an `mg_` gateway API key and writes the
15
+ harness config (`~/.claude/settings.json` for Claude Code,
16
+ `~/.codex/config.toml` for Codex).
17
+ 3. `mgw doctor` — probes the gateway to confirm the harness is routed.
18
+ 4. `mgw status` — reports login + harness configuration state.
19
+ 5. `mgw agent signup|whoami|claim-url|forget` — the no-human path: the agent
20
+ creates a zero-member, capped organization via `POST /agent/signup` on the
21
+ control plane, stores the key in `~/.mgw/agent.json`, and hands its user a
22
+ claim URL. Mirrors `merge agent signup` in merge-cli so the two CLIs can
23
+ consolidate later.
24
+
25
+ Full design lives in the `merge-gateway` repo:
26
+ `docs/superpowers/specs/2026-07-22-cli-harness-onboarding-design.md`.
27
+
28
+ This CLI is a sibling to `merge-api/merge-cli` (the Agent Handler CLI). Both are
29
+ Python, share the same OAuth authorization server, and are structured so they
30
+ can be consolidated into one CLI later — keep patterns aligned where practical.
31
+
32
+ ## Development commands
33
+
34
+ We use [uv](https://docs.astral.sh/uv/) for everything.
35
+
36
+ ```bash
37
+ uv sync --locked # install deps into .venv from the lockfile
38
+ make run ARGS="--version" # run the CLI (uv run mgw ...)
39
+ make tests # uv run pytest -q
40
+ make fmt # uv run ruff format .
41
+ make lint # uv run ruff check . && ruff format --check .
42
+ ```
43
+
44
+ ## Architecture
45
+
46
+ ```
47
+ mgw/
48
+ __init__.py # package + __version__
49
+ cli.py # top-level Click group + command registration
50
+ config.py # ~/.mgw/settings.json overrides (env > file > default)
51
+ commands/ # login, logout, setup, doctor, keys, agent
52
+ harness/ # config writers: claude-code (JSON), codex (TOML)
53
+ tests/ # pytest, mirrors the package layout
54
+ ```
55
+
56
+ Planned modules, added as implementation proceeds:
57
+
58
+ - `mgw/api.py` — thin control-plane HTTP client (httpx) for key minting
59
+ - `mgw/harness/` — one writer per supported harness
60
+
61
+ ## Repo rules
62
+
63
+ - **Test-first (TDD).** Write the failing test, watch it fail, then write the
64
+ minimal code to pass. No production code without a failing test first.
65
+ - **Format and lint before committing:** `make fmt` and `make lint` must pass
66
+ (ruff is both formatter and linter here).
67
+ - **Keep comments and descriptions concise.** Docstrings, Makefile target
68
+ descriptions, workflow step names, and PR text should say what's needed in as
69
+ few words as possible — one tight sentence over a paragraph, and don't restate
70
+ what the code or name already conveys.
71
+ - **Prefer the standard library; justify every dependency.** The runtime deps
72
+ are intentionally few — `click` (command surface), `httpx` (HTTP; matches
73
+ merge-cli), and `tomlkit` (round-trip Codex `config.toml` without clobbering
74
+ the user's comments). Adding a dependency needs a reason in the PR.
75
+ - **Pin everything.** Runtime and dev deps are pinned to exact versions
76
+ (`==`) in `pyproject.toml`, and `uv.lock` hash-pins the full transitive tree —
77
+ commit it. GitHub Actions are pinned to full commit SHAs with a version
78
+ comment (e.g. `actions/checkout@<sha> # v4.2.2`); Dependabot proposes bumps.
79
+ No mutable major-tag action refs, no unpinned modules.
80
+ - **No secrets in the repo or logs.** Never print tokens or the `mg_` key.
81
+ Credentials live under `~/.mgw`, files written mode `0600`.
82
+ - **Thin client:** the durable contract is the control-plane API + the harness
83
+ config-file formats, not this CLI's internals. Keep commands small and keep
84
+ the harness writers behind a clear interface so new harnesses are additive.
85
+ - **Branching:** single `main` trunk — branch off `main`, open PRs into `main`.
86
+ There is no `develop` branch (a CLI releases from tags, not branch pushes).
87
+ Releases will be cut by tagging `main` (`vX.Y.Z` stable, `vX.Y.Z-rc.N`
88
+ pre-release) and published to PyPI.
89
+ - **Distribution:** PyPI package `merge-gateway` (command `mgw`), installable
90
+ via `uv tool install` / `pipx` / `pip`. `.github/workflows/publish.yml` runs
91
+ tests, `uv build`s and publishes with trusted publishing when a GitHub
92
+ **Release** is published — merging to `main` does not publish. Bump
93
+ `__version__` and `pyproject.toml` together, tag `vX.Y.Z`, cut the release.
94
+ - **Config writers must be safe:** always back up an existing config file and
95
+ merge (never clobber) before writing; re-running `setup` must be idempotent.
@@ -0,0 +1 @@
1
+ AGENTS.md
@@ -0,0 +1,28 @@
1
+ .PHONY: help sync fmt lint tests run build clean
2
+
3
+ help: ## Show this help
4
+ @grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
5
+ awk 'BEGIN {FS = ":.*?## "}; {printf " %-10s %s\n", $$1, $$2}'
6
+
7
+ sync: ## Install deps into .venv from the lockfile
8
+ uv sync --locked
9
+
10
+ fmt: ## Format code
11
+ uv run ruff format .
12
+
13
+ lint: ## Lint (ruff check + format check)
14
+ uv run ruff check .
15
+ uv run ruff format --check .
16
+
17
+ tests: ## Run the test suite
18
+ uv run pytest -q
19
+
20
+ run: ## Run the CLI, e.g. make run ARGS="--version"
21
+ uv run mgw $(ARGS)
22
+
23
+ build: ## Build the wheel/sdist
24
+ uv build
25
+
26
+ clean: ## Remove build and cache artifacts
27
+ rm -rf dist build .pytest_cache .ruff_cache
28
+ find . -type d -name __pycache__ -prune -exec rm -rf {} +
@@ -0,0 +1,84 @@
1
+ Metadata-Version: 2.5
2
+ Name: merge-gateway
3
+ Version: 0.1.0
4
+ Summary: Merge Gateway CLI — route your coding agents (Claude Code, Codex) through Merge Gateway
5
+ Project-URL: Homepage, https://merge.dev
6
+ Project-URL: Repository, https://github.com/merge-api/merge-gateway-cli
7
+ Project-URL: Bug Tracker, https://github.com/merge-api/merge-gateway-cli/issues
8
+ Author-email: Merge <support@merge.dev>
9
+ License-Expression: MIT
10
+ Keywords: claude-code,cli,codex,gateway,llm,merge
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3.10
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Requires-Python: >=3.10
19
+ Requires-Dist: click==8.4.2
20
+ Requires-Dist: httpx==0.28.1
21
+ Requires-Dist: tomlkit==0.15.1
22
+ Description-Content-Type: text/markdown
23
+
24
+ # merge-gateway-cli
25
+
26
+ `mgw` — the Merge Gateway CLI. Route your existing coding agents
27
+ (Claude Code, Codex) through [Merge Gateway](https://merge.dev) without editing
28
+ config files by hand.
29
+
30
+ ## Install
31
+
32
+ ```bash
33
+ pipx install merge-gateway # recommended (isolated env)
34
+ pip install merge-gateway # alternative
35
+ ```
36
+
37
+ ## What it does
38
+
39
+ 1. `mgw login` — sign in through your browser (loopback + PKCE), storing a
40
+ short-lived credential under `~/.mgw`.
41
+ 2. `mgw setup <harness>` — mint a gateway API key and write the harness config
42
+ (`claude-code` → `~/.claude/settings.json`, `codex` → `~/.codex/config.toml`).
43
+ 3. `mgw doctor` — confirm the harness routes through the gateway.
44
+ 4. `mgw keys list|rm` — manage the keys mgw minted; `mgw logout` clears local state.
45
+
46
+ ## No human at the keyboard? `mgw agent signup`
47
+
48
+ An AI agent can set itself up without anyone opening a browser:
49
+
50
+ ```bash
51
+ mgw agent signup # creates an organization, saves a key, writes the harness config
52
+ mgw doctor # confirms the gateway routes
53
+ mgw agent whoami # what the saved credential is for (validates it with the server)
54
+ mgw agent claim-url # a fresh claim link for your user (revokes the previous one)
55
+ mgw agent forget # drop the local credentials (nothing is revoked server-side)
56
+ ```
57
+
58
+ `signup` prints a **claim URL**. The organization it created has nobody in it
59
+ and runs as a **sandbox** (a small lifetime budget, a daily request cap and a
60
+ cheap-model allowlist) until a person opens that link, signs up or logs in,
61
+ and becomes its admin — at which point the ordinary account flow (phone
62
+ verification, payment method) lifts the limits. The API key is written to
63
+ `~/.mgw/agent.json` with `0600` permissions and is never printed; pass `--json`
64
+ for machine-readable output (the key is excluded there too).
65
+
66
+ Signup is rate limited per address and fleet-wide; if it is refused, the
67
+ message says why. Re-running `signup` on a machine that already has agent
68
+ credentials is refused — use `whoami` to reuse them.
69
+
70
+ Set `MGW_CONTROL_PLANE_URL` / `MGW_GATEWAY_URL` to target a non-production
71
+ environment (e.g. `https://api-gateway-develop.merge.dev` for both).
72
+
73
+ ## Development
74
+
75
+ We use [uv](https://docs.astral.sh/uv/).
76
+
77
+ ```bash
78
+ uv sync --locked # create .venv from the lockfile
79
+ make run ARGS="--version" # run the CLI
80
+ make tests # run tests
81
+ make lint # ruff check + format check
82
+ ```
83
+
84
+ See [AGENTS.md](./AGENTS.md) for repository conventions.
@@ -0,0 +1,61 @@
1
+ # merge-gateway-cli
2
+
3
+ `mgw` — the Merge Gateway CLI. Route your existing coding agents
4
+ (Claude Code, Codex) through [Merge Gateway](https://merge.dev) without editing
5
+ config files by hand.
6
+
7
+ ## Install
8
+
9
+ ```bash
10
+ pipx install merge-gateway # recommended (isolated env)
11
+ pip install merge-gateway # alternative
12
+ ```
13
+
14
+ ## What it does
15
+
16
+ 1. `mgw login` — sign in through your browser (loopback + PKCE), storing a
17
+ short-lived credential under `~/.mgw`.
18
+ 2. `mgw setup <harness>` — mint a gateway API key and write the harness config
19
+ (`claude-code` → `~/.claude/settings.json`, `codex` → `~/.codex/config.toml`).
20
+ 3. `mgw doctor` — confirm the harness routes through the gateway.
21
+ 4. `mgw keys list|rm` — manage the keys mgw minted; `mgw logout` clears local state.
22
+
23
+ ## No human at the keyboard? `mgw agent signup`
24
+
25
+ An AI agent can set itself up without anyone opening a browser:
26
+
27
+ ```bash
28
+ mgw agent signup # creates an organization, saves a key, writes the harness config
29
+ mgw doctor # confirms the gateway routes
30
+ mgw agent whoami # what the saved credential is for (validates it with the server)
31
+ mgw agent claim-url # a fresh claim link for your user (revokes the previous one)
32
+ mgw agent forget # drop the local credentials (nothing is revoked server-side)
33
+ ```
34
+
35
+ `signup` prints a **claim URL**. The organization it created has nobody in it
36
+ and runs as a **sandbox** (a small lifetime budget, a daily request cap and a
37
+ cheap-model allowlist) until a person opens that link, signs up or logs in,
38
+ and becomes its admin — at which point the ordinary account flow (phone
39
+ verification, payment method) lifts the limits. The API key is written to
40
+ `~/.mgw/agent.json` with `0600` permissions and is never printed; pass `--json`
41
+ for machine-readable output (the key is excluded there too).
42
+
43
+ Signup is rate limited per address and fleet-wide; if it is refused, the
44
+ message says why. Re-running `signup` on a machine that already has agent
45
+ credentials is refused — use `whoami` to reuse them.
46
+
47
+ Set `MGW_CONTROL_PLANE_URL` / `MGW_GATEWAY_URL` to target a non-production
48
+ environment (e.g. `https://api-gateway-develop.merge.dev` for both).
49
+
50
+ ## Development
51
+
52
+ We use [uv](https://docs.astral.sh/uv/).
53
+
54
+ ```bash
55
+ uv sync --locked # create .venv from the lockfile
56
+ make run ARGS="--version" # run the CLI
57
+ make tests # run tests
58
+ make lint # ruff check + format check
59
+ ```
60
+
61
+ See [AGENTS.md](./AGENTS.md) for repository conventions.
@@ -0,0 +1,3 @@
1
+ """mgw — the Merge Gateway CLI."""
2
+
3
+ __version__ = "0.1.0"