substrate-setup 0.3.0__tar.gz → 0.4.0__tar.gz

{substrate_setup-0.3.0 → substrate_setup-0.4.0}/.gitignore

@@ -1,77 +1,77 @@
-# Secrets
-.env
-.env.local
-.env.*.local
-*.secret
-secrets/
-credentials.txt
-credentials.*.txt
-
-# Python
-__pycache__/
-*.py[cod]
-*$py.class
-*.so
-.Python
-.venv/
-venv/
-env/
-.pytest_cache/
-.mypy_cache/
-.ruff_cache/
-*.egg-info/
-dist/
-build/
-
-# Node / Next.js
-node_modules/
-.next/
-.vercel/
-.turbo/
-
-# CodeGraph (local-only code knowledge graph index)
-.codegraph/
-out/
-*.tsbuildinfo
-.npm/
-.yarn/
-
-# IDE
-.vscode/
-.idea/
-*.swp
-*.swo
-
-# OS
-.DS_Store
-Thumbs.db
-desktop.ini
-
-# Logs
-*.log
-logs/
-
-# Local databases
-*.db
-*.sqlite
-*.sqlite3
-
-# Editors
-*~
-.#*
-
-# Coverage
-.coverage
-htmlcov/
-coverage.xml
-*.cover
-
-# Claude Code project state (if any project-local)
-.claude/
-
-# Misc
-*.bak
-*.tmp
-
-# brainstorming companion working dir
-.superpowers/
+# Secrets
+.env
+.env.local
+.env.*.local
+*.secret
+secrets/
+credentials.txt
+credentials.*.txt
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv/
+venv/
+env/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/
+dist/
+build/
+
+# Node / Next.js
+node_modules/
+.next/
+.vercel/
+.turbo/
+
+# CodeGraph (local-only code knowledge graph index)
+.codegraph/
+out/
+*.tsbuildinfo
+.npm/
+.yarn/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Logs
+*.log
+logs/
+
+# Local databases
+*.db
+*.sqlite
+*.sqlite3
+
+# Editors
+*~
+.#*
+
+# Coverage
+.coverage
+htmlcov/
+coverage.xml
+*.cover
+
+# Claude Code project state (if any project-local)
+.claude/
+
+# Misc
+*.bak
+*.tmp
+
+# brainstorming companion working dir
+.superpowers/

substrate_setup-0.4.0/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+## 0.4.0 — 2026-05-30
+
+- Lower the supported Python floor from **3.12 to 3.8**. Nothing in the tool
+  actually required 3.12 — the gate was conservative. `pip install
+  substrate-setup` now works on Anaconda's default 3.9 and other older
+  interpreters, no `uv`/`pipx` workaround needed.
+  - `enum.StrEnum` (3.11+) imports natively on 3.11+ with a minimal
+    `(str, Enum)` backport on older interpreters.
+  - The `tomllib` → `tomli` fallback is now `sys.version_info`-gated, and
+    `tomli` is a declared dependency (`python_version < '3.11'`) — previously
+    the fallback path had no dependency backing it and would have failed.
+  - `tomli-w` lower bound relaxed `1.2 → 1.0` so 3.8 resolves.
+- No CLI or config-schema changes — pure compatibility widening. The
+  test/type tooling still requires 3.9+ (`pytest-httpx`/`mypy` dropped 3.8);
+  end users on 3.8 are unaffected.
+
+## 0.3.1 — 2026-05-24
+
+- Persist `SUBSTRATE_API_KEY` automatically during `configure`:
+  on Windows, writes `HKCU\Environment\SUBSTRATE_API_KEY` via `winreg`
+  + `WM_SETTINGCHANGE` broadcast — visible to GUI agents (Codex Desktop)
+  on next launch without the user editing rc files or restarting their
+  session. On macOS / Linux, appends a marker-fenced `export` block (or
+  fish-syntax `set -gx` for fish users) to the user's shell rc. Re-runs
+  collapse stale blocks idempotently — the rc never grows on repeated
+  configures.
+- Codex adapter now prints a one-line Windows Defender exclusion command
+  to eliminate SmartScreen prompts on per-action helper binary spawns.
+  Informational only — substrate-setup never elevates itself.
+- Adapters surface env-persistence failures with a clear `WARNING:`
+  prefix + manual fallback hint so users notice when the convenience
+  step fails but the config file itself was written successfully.
+- Codex adapter drops the stale "/v1/responses NOT YET STARTED" warning
+  — Phase 2 shipped on 2026-05-24.
+- No config schema changes from 0.3.0. Upgrade cleanly via
+  `uv tool install --force substrate-setup` (or pipx).

{substrate_setup-0.3.0 → substrate_setup-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: substrate-setup
-Version: 0.3.0
+Version: 0.4.0
 Summary: One-shot local configurator for coding agents against a Substrate gateway
 Project-URL: Homepage, https://github.com/FrankXiaA/substrate-solutions
 Project-URL: Source, https://github.com/FrankXiaA/substrate-solutions/tree/main/substrate-api/substrate_setup
@@ -14,16 +14,21 @@ Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development :: Code Generators
 Classifier: Topic :: Utilities
-Requires-Python: >=3.12
+Requires-Python: >=3.8
 Requires-Dist: httpx>=0.27
 Requires-Dist: ruamel-yaml>=0.18
-Requires-Dist: tomli-w>=1.2
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
 Provides-Extra: dev
 Requires-Dist: mypy<2,>=1.13; extra == 'dev'
-Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30; (python_version >= '3.9') and extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff<1,>=0.7; extra == 'dev'
 Description-Content-Type: text/markdown
@@ -34,10 +39,16 @@ One-shot configurator that points local coding agents at a Substrate gateway.
 
 ## Install
 
-`substrate-setup` requires Python 3.12+. The installers below pick the right interpreter automatically — you don't need a Python 3.12 already on your machine:
+`substrate-setup` runs on **Python 3.8 or newer** — including Anaconda's default 3.9 and the system Python on older Linux/macOS boxes. Plain `pip` works:
 
 ```bash
-# Option A — uv (recommended; downloads Python 3.12 on demand if missing)
+pip install substrate-setup
+```
+
+If you'd rather keep the tool in its own isolated environment (recommended, so it can't clash with a project's dependencies), use `uv` or `pipx`:
+
+```bash
+# Option A — uv (also downloads a Python for the tool if needed)
 uv tool install substrate-setup
 
 # Option B — pipx
@@ -52,19 +63,24 @@ curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS / Linux
 powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
 ```
 
-> **Why not `pip install substrate-setup`?** It works only if the `pip` on your PATH is bound to a Python 3.12+ interpreter. Anaconda's default `pip` (Python 3.9) is the common pitfall — PyPI hides every release from it with `Requires-Python >=3.12` and the error message is unhelpful. `uv` and `pipx` both create an isolated 3.12 venv for the tool, so they sidestep the issue entirely.
-
 ## Use
 
 ```bash
-export SUBSTRATE_API_KEY="sk-substrate-..."   # or be prompted
-
 substrate-setup configure          # detect installed agents and wire them up
 substrate-setup verify             # read-only: confirm everything points at the gateway
 substrate-setup remove             # strip the substrate-managed entries
 substrate-setup --help
 ```
 
+### After running configure
+
+`substrate-setup configure` writes the API key for you automatically. On Windows it lands in `HKCU\Environment\SUBSTRATE_API_KEY` (visible to Codex Desktop and other GUI agents on next launch). On macOS / Linux it lands in your shell rc (`~/.zshrc`, `~/.bashrc`, or `~/.config/fish/config.fish` depending on `$SHELL`) inside a marker-fenced block — re-running configure replaces the block in place, no duplicates.
+
+You should not need to set `SUBSTRATE_API_KEY` by hand. If auto-persistence fails (the printed message will say `API key WARNING: …`), you can set it manually:
+
+- **Windows:** `[Environment]::SetEnvironmentVariable("SUBSTRATE_API_KEY", "<your-key>", "User")` then re-launch the agent.
+- **macOS / Linux:** add `export SUBSTRATE_API_KEY=<your-key>` to your shell rc and `source` it.
+
 Supported agents: `hermes`, `cursor`, `aider`, `continue`, `claude-code`, `codex`.
 
 Subset with `--agents-only hermes,aider`. Preview without writing: `--dry-run`. Override the gateway base URL: `--base-url https://your-gateway.example.com`.
@@ -77,5 +93,33 @@ Subset with `--agents-only hermes,aider`. Preview without writing: `--dry-run`.
 | `cursor` | Walkthrough printed after configure — copy the base URL, key, and model ids into Cursor's Settings → Models. |
 | `aider` | `~/.aider.model.metadata.json` written with one entry per chat-capable Substrate model. Use `--model openai/<id>` to switch. |
 | `continue` | All chat-capable Substrate models written as separate `models:` entries in `~/.continue/config.yaml`. |
-| `claude-code` | `~/.claude/settings.json` env block (`ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_MODEL`). The `/model` picker stays opus/sonnet/haiku — use `claude --model openai/<id>` for any other Substrate model. **Note:** requires Substrate's `/v1/messages` endpoint, which is gated behind a Fly feature flag — until it's flipped, requests return 404. |
-| `codex` | `~/.codex/config.toml` `[model_providers.substrate]` block with `wire_api = "responses"`. Set `SUBSTRATE_API_KEY` in your shell rc. **Note:** requires Substrate's `/v1/responses` endpoint (gateway protocol adapters Phase 2 — not yet started). |
+| `claude-code` | `~/.claude/settings.json` env block (`ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_MODEL`). The `/model` picker stays opus/sonnet/haiku — use `claude --model openai/<id>` for any other Substrate model. Requires Substrate's `/v1/messages` endpoint — shipped in gateway Phase 1. |
+| `codex` | `~/.codex/config.toml` `[model_providers.substrate]` block with `wire_api = "responses"`. API key is auto-persisted (see above). Requires Substrate's `/v1/responses` endpoint — shipped in gateway Phase 2. |
+
+### Heads-up: tool calling on Gemini 3.1 Pro Preview
+
+If your CLI agent (Hermes, Aider, etc.) uses tool calling against
+`google/gemini-3.1-pro-preview`, expect occasional misses (~20-30% of
+attempts). All other Substrate models hit ≥95% reliability for tool calls.
+
+## Troubleshooting
+
+### Windows: Defender SmartScreen prompts on every Codex click
+
+Codex Desktop spawns helper binaries (`codex-command-runner.exe`,
+`node_repl.exe`) per UI action. With `sandbox = "elevated"` in
+`~/.codex/config.toml`, each spawn triggers Windows Defender
+SmartScreen, prompting you on every click until the Codex install
+directory is whitelisted.
+
+One-time fix — open an **Administrator** PowerShell window and run:
+
+```powershell
+Add-MpPreference -ExclusionPath "$env:LOCALAPPDATA\OpenAI\Codex"
+```
+
+This excludes Codex's binaries from real-time scanning. Reverse with
+`Remove-MpPreference -ExclusionPath "$env:LOCALAPPDATA\OpenAI\Codex"`.
+
+`substrate-setup configure --agents-only codex` also prints this
+command at the end of its walkthrough on Windows.

substrate_setup-0.4.0/README.md

@@ -0,0 +1,90 @@
+# substrate-setup
+
+One-shot configurator that points local coding agents at a Substrate gateway.
+
+## Install
+
+`substrate-setup` runs on **Python 3.8 or newer** — including Anaconda's default 3.9 and the system Python on older Linux/macOS boxes. Plain `pip` works:
+
+```bash
+pip install substrate-setup
+```
+
+If you'd rather keep the tool in its own isolated environment (recommended, so it can't clash with a project's dependencies), use `uv` or `pipx`:
+
+```bash
+# Option A — uv (also downloads a Python for the tool if needed)
+uv tool install substrate-setup
+
+# Option B — pipx
+pipx install substrate-setup
+```
+
+Don't have `uv`? Install it once with:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS / Linux
+# or on Windows:
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+## Use
+
+```bash
+substrate-setup configure          # detect installed agents and wire them up
+substrate-setup verify             # read-only: confirm everything points at the gateway
+substrate-setup remove             # strip the substrate-managed entries
+substrate-setup --help
+```
+
+### After running configure
+
+`substrate-setup configure` writes the API key for you automatically. On Windows it lands in `HKCU\Environment\SUBSTRATE_API_KEY` (visible to Codex Desktop and other GUI agents on next launch). On macOS / Linux it lands in your shell rc (`~/.zshrc`, `~/.bashrc`, or `~/.config/fish/config.fish` depending on `$SHELL`) inside a marker-fenced block — re-running configure replaces the block in place, no duplicates.
+
+You should not need to set `SUBSTRATE_API_KEY` by hand. If auto-persistence fails (the printed message will say `API key WARNING: …`), you can set it manually:
+
+- **Windows:** `[Environment]::SetEnvironmentVariable("SUBSTRATE_API_KEY", "<your-key>", "User")` then re-launch the agent.
+- **macOS / Linux:** add `export SUBSTRATE_API_KEY=<your-key>` to your shell rc and `source` it.
+
+Supported agents: `hermes`, `cursor`, `aider`, `continue`, `claude-code`, `codex`.
+
+Subset with `--agents-only hermes,aider`. Preview without writing: `--dry-run`. Override the gateway base URL: `--base-url https://your-gateway.example.com`.
+
+### Per-agent catalog UX (0.3.0+)
+
+| Agent | How it learns about Substrate's models |
+|---|---|
+| `hermes` | Live URL fetch via `model_catalog.providers.substrate.url`. Picker shows all chat-capable Substrate models, refreshed on Hermes' 24h TTL. |
+| `cursor` | Walkthrough printed after configure — copy the base URL, key, and model ids into Cursor's Settings → Models. |
+| `aider` | `~/.aider.model.metadata.json` written with one entry per chat-capable Substrate model. Use `--model openai/<id>` to switch. |
+| `continue` | All chat-capable Substrate models written as separate `models:` entries in `~/.continue/config.yaml`. |
+| `claude-code` | `~/.claude/settings.json` env block (`ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_MODEL`). The `/model` picker stays opus/sonnet/haiku — use `claude --model openai/<id>` for any other Substrate model. Requires Substrate's `/v1/messages` endpoint — shipped in gateway Phase 1. |
+| `codex` | `~/.codex/config.toml` `[model_providers.substrate]` block with `wire_api = "responses"`. API key is auto-persisted (see above). Requires Substrate's `/v1/responses` endpoint — shipped in gateway Phase 2. |
+
+### Heads-up: tool calling on Gemini 3.1 Pro Preview
+
+If your CLI agent (Hermes, Aider, etc.) uses tool calling against
+`google/gemini-3.1-pro-preview`, expect occasional misses (~20-30% of
+attempts). All other Substrate models hit ≥95% reliability for tool calls.
+
+## Troubleshooting
+
+### Windows: Defender SmartScreen prompts on every Codex click
+
+Codex Desktop spawns helper binaries (`codex-command-runner.exe`,
+`node_repl.exe`) per UI action. With `sandbox = "elevated"` in
+`~/.codex/config.toml`, each spawn triggers Windows Defender
+SmartScreen, prompting you on every click until the Codex install
+directory is whitelisted.
+
+One-time fix — open an **Administrator** PowerShell window and run:
+
+```powershell
+Add-MpPreference -ExclusionPath "$env:LOCALAPPDATA\OpenAI\Codex"
+```
+
+This excludes Codex's binaries from real-time scanning. Reverse with
+`Remove-MpPreference -ExclusionPath "$env:LOCALAPPDATA\OpenAI\Codex"`.
+
+`substrate-setup configure --agents-only codex` also prints this
+command at the end of its walkthrough on Windows.

{substrate_setup-0.3.0 → substrate_setup-0.4.0}/pyproject.toml

@@ -1,63 +1,80 @@
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[project]
-name = "substrate-setup"
-version = "0.3.0"
-description = "One-shot local configurator for coding agents against a Substrate gateway"
-readme = "README.md"
-requires-python = ">=3.12"
-authors = [{ name = "Substrate Solutions" }]
-license = { text = "MIT" }
-keywords = ["substrate", "llm", "gateway", "aider", "continue", "hermes", "openai-compatible"]
-classifiers = [
-  "Development Status :: 4 - Beta",
-  "Environment :: Console",
-  "Intended Audience :: Developers",
-  "License :: OSI Approved :: MIT License",
-  "Operating System :: OS Independent",
-  "Programming Language :: Python :: 3 :: Only",
-  "Programming Language :: Python :: 3.12",
-  "Topic :: Software Development :: Code Generators",
-  "Topic :: Utilities",
-]
-dependencies = [
-  "httpx>=0.27",
-  "ruamel.yaml>=0.18",
-  "tomli-w>=1.2",
-]
-
-[project.urls]
-Homepage = "https://github.com/FrankXiaA/substrate-solutions"
-Source = "https://github.com/FrankXiaA/substrate-solutions/tree/main/substrate-api/substrate_setup"
-Issues = "https://github.com/FrankXiaA/substrate-solutions/issues"
-
-[project.optional-dependencies]
-dev = [
-  "pytest>=8.0",
-  "pytest-httpx>=0.30",
-  "ruff>=0.7,<1",
-  "mypy>=1.13,<2",
-]
-
-[project.scripts]
-substrate-setup = "substrate_setup.cli:main"
-
-[tool.hatch.build.targets.wheel]
-packages = ["substrate_setup"]
-
-[tool.pytest.ini_options]
-testpaths = ["tests"]
-
-[tool.mypy]
-python_version = "3.12"
-strict = true
-ignore_missing_imports = true
-packages = ["substrate_setup"]
-
-[[tool.mypy.overrides]]
-module = "tests.*"
-disallow_untyped_defs = false
-disallow_incomplete_defs = false
-check_untyped_defs = false
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "substrate-setup"
+version = "0.4.0"
+description = "One-shot local configurator for coding agents against a Substrate gateway"
+readme = "README.md"
+requires-python = ">=3.8"
+authors = [{ name = "Substrate Solutions" }]
+license = { text = "MIT" }
+keywords = ["substrate", "llm", "gateway", "aider", "continue", "hermes", "openai-compatible"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Code Generators",
+  "Topic :: Utilities",
+]
+dependencies = [
+  "httpx>=0.27",
+  "ruamel.yaml>=0.18",
+  "tomli-w>=1.0",
+  # Reading TOML (codex config, credentials probe) uses the stdlib
+  # ``tomllib`` on 3.11+; older interpreters fall back to the ``tomli``
+  # backport. See ``credentials.py`` / ``agents/codex.py`` import guards.
+  "tomli>=2.0; python_version < '3.11'",
+]
+
+[project.urls]
+Homepage = "https://github.com/FrankXiaA/substrate-solutions"
+Source = "https://github.com/FrankXiaA/substrate-solutions/tree/main/substrate-api/substrate_setup"
+Issues = "https://github.com/FrankXiaA/substrate-solutions/issues"
+
+[project.optional-dependencies]
+# Runtime floor is Python 3.8, but the test/type tooling needs 3.9+
+# (pytest-httpx>=0.30 and modern mypy both dropped 3.8). Developing/testing
+# the package therefore requires 3.9+; end users on 3.8 are unaffected.
+dev = [
+  "pytest>=8.0",
+  "pytest-httpx>=0.30; python_version >= '3.9'",
+  "ruff>=0.7,<1",
+  "mypy>=1.13,<2",
+]
+
+[project.scripts]
+substrate-setup = "substrate_setup.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["substrate_setup"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py38"
+
+[tool.mypy]
+# Lowest version mypy itself supports as an analysis target; the package's
+# runtime floor is 3.8 (see requires-python). 3.8-only breakage is caught by
+# the test suite + import smoke, not the type checker.
+python_version = "3.9"
+strict = true
+ignore_missing_imports = true
+packages = ["substrate_setup"]
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+disallow_incomplete_defs = false
+check_untyped_defs = false

{substrate_setup-0.3.0 → substrate_setup-0.4.0}/scripts/lint_no_app_import.sh

@@ -1,10 +1,10 @@
-#!/usr/bin/env bash
-# CI lint: substrate_setup/ MUST NOT import anything from app/.
-# The two packages share a source tree, not a dependency graph.
-set -euo pipefail
-PKG_DIR="$(cd "$(dirname "$0")/.." && pwd)"
-if grep -RIn --include='*.py' '^from app\b\|^import app\b' "$PKG_DIR/substrate_setup"; then
-    echo "ERROR: substrate_setup/ must not import from app/. See package boundary rule in spec."
-    exit 1
-fi
-echo "OK: no app/ imports in substrate_setup/"
+#!/usr/bin/env bash
+# CI lint: substrate_setup/ MUST NOT import anything from app/.
+# The two packages share a source tree, not a dependency graph.
+set -euo pipefail
+PKG_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+if grep -RIn --include='*.py' '^from app\b\|^import app\b' "$PKG_DIR/substrate_setup"; then
+    echo "ERROR: substrate_setup/ must not import from app/. See package boundary rule in spec."
+    exit 1
+fi
+echo "OK: no app/ imports in substrate_setup/"