substrate-setup 0.2.0__tar.gz → 0.2.2__tar.gz

{substrate_setup-0.2.0 → substrate_setup-0.2.2}/.gitignore

@@ -1,74 +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
+# 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.2.2/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: substrate-setup
+Version: 0.2.2
+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
+Project-URL: Issues, https://github.com/FrankXiaA/substrate-solutions/issues
+Author: Substrate Solutions
+License: MIT
+Keywords: aider,continue,gateway,hermes,llm,openai-compatible,substrate
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+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.12
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: ruamel-yaml>=0.18
+Provides-Extra: dev
+Requires-Dist: mypy<2,>=1.13; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff<1,>=0.7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# substrate-setup
+
+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:
+
+```bash
+# Option A — uv (recommended; downloads Python 3.12 on demand if missing)
+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"
+```
+
+> **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
+```
+
+Supported agents: `hermes`, `cursor`, `aider`, `continue`.
+
+Subset with `--agents-only hermes,aider`. Preview without writing: `--dry-run`. Override the gateway base URL: `--base-url https://your-gateway.example.com`.

substrate_setup-0.2.2/README.md

@@ -0,0 +1,40 @@
+# substrate-setup
+
+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:
+
+```bash
+# Option A — uv (recommended; downloads Python 3.12 on demand if missing)
+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"
+```
+
+> **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
+```
+
+Supported agents: `hermes`, `cursor`, `aider`, `continue`.
+
+Subset with `--agents-only hermes,aider`. Preview without writing: `--dry-run`. Override the gateway base URL: `--base-url https://your-gateway.example.com`.

{substrate_setup-0.2.0 → substrate_setup-0.2.2}/pyproject.toml

@@ -1,62 +1,62 @@
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[project]
-name = "substrate-setup"
-version = "0.2.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",
-]
-
-[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.2.2"
+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",
+]
+
+[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

{substrate_setup-0.2.0 → substrate_setup-0.2.2}/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/"

{substrate_setup-0.2.0 → substrate_setup-0.2.2}/scripts/regenerate_fallback_catalog.py

@@ -1,68 +1,68 @@
-"""Regenerate the bundled fallback catalog snapshot.
-
-Run manually before each PyPI release of substrate-setup. NOT run by CI cron —
-a transient production glitch should NEVER be baked into the next release.
-
-Usage:
-    SUBSTRATE_API_KEY=sk-substrate-... \
-        python scripts/regenerate_fallback_catalog.py [--base-url https://...]
-
-Writes substrate_setup/data/fallback_catalog.json. Applies a sanity check
-(>= 5 models, all five expected providers present) before writing.
-"""
-from __future__ import annotations
-
-import argparse
-import json
-import os
-import sys
-from pathlib import Path
-
-import httpx
-
-EXPECTED_PROVIDERS = {"anthropic", "openai", "google", "deepseek", "moonshot"}
-DEFAULT_BASE_URL = "https://substrate-solutions-api.fly.dev/v1"
-TARGET = Path(__file__).resolve().parents[1] / "substrate_setup" / "data" / "fallback_catalog.json"
-
-
-def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser()
-    parser.add_argument("--base-url", default=DEFAULT_BASE_URL)
-    args = parser.parse_args(argv)
-
-    api_key = os.environ.get("SUBSTRATE_API_KEY")
-    if not api_key:
-        print("ERROR: SUBSTRATE_API_KEY env var required.", file=sys.stderr)
-        return 1
-
-    # Tolerate --base-url with or without a trailing /v1 (same convention as
-    # substrate_setup.catalog.fetch_catalog).
-    normalized = args.base_url.rstrip("/")
-    if normalized.endswith("/v1"):
-        normalized = normalized[:-3]
-
-    resp = httpx.get(
-        f"{normalized}/v1/models",
-        headers={"Authorization": f"Bearer {api_key}"},
-        timeout=15.0,
-    )
-    resp.raise_for_status()
-    payload = resp.json()
-
-    data = payload.get("data") or []
-    providers = {item.get("owned_by") for item in data}
-    if len(data) < 5:
-        print(f"REFUSED: only {len(data)} models in catalog (expected >= 5).", file=sys.stderr)
-        return 2
-    if not EXPECTED_PROVIDERS.issubset(providers):
-        missing = EXPECTED_PROVIDERS - providers
-        print(f"REFUSED: missing providers {missing}.", file=sys.stderr)
-        return 2
-
-    TARGET.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
-    print(f"Wrote {len(data)} models to {TARGET}")
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())
+"""Regenerate the bundled fallback catalog snapshot.
+
+Run manually before each PyPI release of substrate-setup. NOT run by CI cron —
+a transient production glitch should NEVER be baked into the next release.
+
+Usage:
+    SUBSTRATE_API_KEY=sk-substrate-... \
+        python scripts/regenerate_fallback_catalog.py [--base-url https://...]
+
+Writes substrate_setup/data/fallback_catalog.json. Applies a sanity check
+(>= 5 models, all five expected providers present) before writing.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+import httpx
+
+EXPECTED_PROVIDERS = {"anthropic", "openai", "google", "deepseek", "moonshot"}
+DEFAULT_BASE_URL = "https://substrate-solutions-api.fly.dev/v1"
+TARGET = Path(__file__).resolve().parents[1] / "substrate_setup" / "data" / "fallback_catalog.json"
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--base-url", default=DEFAULT_BASE_URL)
+    args = parser.parse_args(argv)
+
+    api_key = os.environ.get("SUBSTRATE_API_KEY")
+    if not api_key:
+        print("ERROR: SUBSTRATE_API_KEY env var required.", file=sys.stderr)
+        return 1
+
+    # Tolerate --base-url with or without a trailing /v1 (same convention as
+    # substrate_setup.catalog.fetch_catalog).
+    normalized = args.base_url.rstrip("/")
+    if normalized.endswith("/v1"):
+        normalized = normalized[:-3]
+
+    resp = httpx.get(
+        f"{normalized}/v1/models",
+        headers={"Authorization": f"Bearer {api_key}"},
+        timeout=15.0,
+    )
+    resp.raise_for_status()
+    payload = resp.json()
+
+    data = payload.get("data") or []
+    providers = {item.get("owned_by") for item in data}
+    if len(data) < 5:
+        print(f"REFUSED: only {len(data)} models in catalog (expected >= 5).", file=sys.stderr)
+        return 2
+    if not EXPECTED_PROVIDERS.issubset(providers):
+        missing = EXPECTED_PROVIDERS - providers
+        print(f"REFUSED: missing providers {missing}.", file=sys.stderr)
+        return 2
+
+    TARGET.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+    print(f"Wrote {len(data)} models to {TARGET}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{substrate_setup-0.2.0 → substrate_setup-0.2.2}/substrate_setup/__init__.py

@@ -1,6 +1,6 @@
-"""substrate-setup — one-shot configurator for coding agents.
-
-See https://github.com/FrankXiaA/substrate-solutions for the gateway it
-configures against.
-"""
-__version__ = "0.2.0"
+"""substrate-setup — one-shot configurator for coding agents.
+
+See https://github.com/FrankXiaA/substrate-solutions for the gateway it
+configures against.
+"""
+__version__ = "0.2.2"

{substrate_setup-0.2.0 → substrate_setup-0.2.2}/substrate_setup/__main__.py

@@ -1,5 +1,5 @@
-"""Module entry point: ``python -m substrate_setup``."""
-from substrate_setup.cli import main
-
-if __name__ == "__main__":
-    raise SystemExit(main())
+"""Module entry point: ``python -m substrate_setup``."""
+from substrate_setup.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{substrate_setup-0.2.0 → substrate_setup-0.2.2}/substrate_setup/agents/__init__.py

@@ -1,20 +1,20 @@
-"""Agent registry. Imports each agent module; exposes the list.
-
-Order of this list is the order they print in the summary.
-"""
-from __future__ import annotations
-
-from substrate_setup.agents.aider import AiderAgent
-from substrate_setup.agents.base import Agent
-from substrate_setup.agents.continue_dev import ContinueAgent
-from substrate_setup.agents.cursor import CursorAgent
-from substrate_setup.agents.hermes import HermesAgent
-
-ALL_AGENTS: list[Agent] = [
-    HermesAgent(),
-    CursorAgent(),
-    AiderAgent(),
-    ContinueAgent(),
-]
-
-AGENT_NAMES: list[str] = [a.name for a in ALL_AGENTS]
+"""Agent registry. Imports each agent module; exposes the list.
+
+Order of this list is the order they print in the summary.
+"""
+from __future__ import annotations
+
+from substrate_setup.agents.aider import AiderAgent
+from substrate_setup.agents.base import Agent
+from substrate_setup.agents.continue_dev import ContinueAgent
+from substrate_setup.agents.cursor import CursorAgent
+from substrate_setup.agents.hermes import HermesAgent
+
+ALL_AGENTS: list[Agent] = [
+    HermesAgent(),
+    CursorAgent(),
+    AiderAgent(),
+    ContinueAgent(),
+]
+
+AGENT_NAMES: list[str] = [a.name for a in ALL_AGENTS]

{substrate_setup-0.2.0 → substrate_setup-0.2.2}/substrate_setup/agents/aider.py

@@ -120,6 +120,30 @@ def _user_has_meaningful_keys(payload: dict[str, Any]) -> bool:
     return False
 
 
+def _existing_matches_substrate_shape(
+    payload: dict[str, Any], ctx: ConfigureContext
+) -> bool:
+    """True if existing top-level values look substrate-shaped already.
+
+    Specifically:
+      - openai-api-base matches ctx.base_url
+      - openai-api-key starts with "sk-substrate-" (the user may have
+        rotated keys since, so we don't require an exact match)
+
+    Lets us silently take ownership of configs that were either manually
+    configured to match our schema or written by an earlier substrate-setup
+    version that didn't drop the marker. Without this auto-claim, every
+    user upgrading from 0.1 (or who manually fixed their config) sees a
+    refusal ERROR on first 0.2.x run.
+    """
+    if payload.get("openai-api-base") != ctx.base_url:
+        return False
+    api_key = payload.get("openai-api-key")
+    if not isinstance(api_key, str) or not api_key.startswith("sk-substrate-"):
+        return False
+    return True
+
+
 def _pick_default_model(catalog: list[Any]) -> str:
     if not catalog:
         raise ValueError("Cannot pick default model from empty catalog")
@@ -140,13 +164,19 @@ class AiderAgent(Agent):
         payload = _load_yaml(conf)
 
         if not _has_substrate_marker(payload) and _user_has_meaningful_keys(payload):
-            return AgentResult(
-                ResultStatus.ERROR,
-                "Aider ~/.aider.conf.yml has user-owned openai-api-base / "
-                "openai-api-key / model keys but no substrate-setup marker; "
-                "refused to overwrite. To take over, remove those keys (or "
-                "the whole file) and re-run substrate-setup.",
-            )
+            if _existing_matches_substrate_shape(payload, ctx):
+                # Shape already matches us -- silently take ownership.
+                # Fall through to the normal write below, which adds the
+                # marker and refreshes our 3 keys.
+                pass
+            else:
+                return AgentResult(
+                    ResultStatus.ERROR,
+                    "Aider ~/.aider.conf.yml has user-owned openai-api-base / "
+                    "openai-api-key / model keys but no substrate-setup marker; "
+                    "refused to overwrite. To take over, remove those keys (or "
+                    "the whole file) and re-run substrate-setup.",
+                )
 
         if conf.exists():
             backup = backup_once(conf)