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

{substrate_setup-0.2.0 → substrate_setup-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: substrate-setup
-Version: 0.2.0
+Version: 0.2.1
 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

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "substrate-setup"
-version = "0.2.0"
+version = "0.2.1"
 description = "One-shot local configurator for coding agents against a Substrate gateway"
 readme = "README.md"
 requires-python = ">=3.12"

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

@@ -3,4 +3,4 @@
 See https://github.com/FrankXiaA/substrate-solutions for the gateway it
 configures against.
 """
-__version__ = "0.2.0"
+__version__ = "0.2.1"

{substrate_setup-0.2.0 → substrate_setup-0.2.1}/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)

{substrate_setup-0.2.0 → substrate_setup-0.2.1}/substrate_setup/agents/cursor.py

@@ -48,15 +48,15 @@ class CursorAgent(Agent):
             "Cursor detected. Cursor stores its API config in secure OS storage,\n"
             "so substrate-setup cannot write it for you. Open Cursor and:\n"
             "\n"
-            "  1. Settings (⌘/Ctrl-,) → Models\n"
+            "  1. Settings (Cmd/Ctrl-,) -> Models\n"
             "  2. Toggle \"Override OpenAI Base URL\" ON\n"
             f"  3. Paste this Base URL:  {ctx.base_url}\n"
             f"  4. Paste this API Key:   {ctx.api_key}\n"
             "  5. Click \"Verify\"\n"
-            "  6. Add these models (Settings → Models → \"Add Model\"), one at a time:\n"
+            "  6. Add these models (Settings -> Models -> \"Add Model\"), one at a time:\n"
             f"{bullets}\n"
             "\n"
-            "WARNING: enabling \"Override OpenAI Base URL\" is global — it will also\n"
+            "WARNING: enabling \"Override OpenAI Base URL\" is global -- it will also\n"
             "route Cursor's first-party Composer / Tab / Apply features through\n"
             "Substrate, which may not work as expected. This is a Cursor limitation,\n"
             "not a substrate-setup issue."
@@ -68,7 +68,7 @@ class CursorAgent(Agent):
 
     def verify(self, ctx: ConfigureContext) -> AgentResult:
         print(
-            "Cursor: cannot verify automatically — config lives in Cursor's secure storage."
+            "Cursor: cannot verify automatically -- config lives in Cursor's secure storage."
         )
         return AgentResult(
             ResultStatus.PRINT_ONLY,
@@ -79,7 +79,7 @@ class CursorAgent(Agent):
         print(
             "Cursor: substrate-setup cannot remove your config (it lives in secure\n"
             "OS storage). To clean up, open Cursor and:\n"
-            "  1. Settings (⌘/Ctrl-,) → Models\n"
+            "  1. Settings (Cmd/Ctrl-,) -> Models\n"
             "  2. Toggle \"Override OpenAI Base URL\" OFF\n"
             "  3. Clear the OpenAI API Key field\n"
             "  4. Remove the Substrate-added models from the model list."

{substrate_setup-0.2.0 → substrate_setup-0.2.1}/substrate_setup/agents/hermes.py

@@ -195,6 +195,33 @@ def _user_has_meaningful_model_block(payload: dict[str, Any]) -> bool:
     return False
 
 
+def _existing_matches_substrate_shape(
+    model: dict[str, Any], ctx: ConfigureContext
+) -> bool:
+    """True if existing model.* values look substrate-shaped already.
+
+    Specifically:
+      - provider == "custom"
+      - base_url matches ctx.base_url
+      - api_key starts with "sk-substrate-" (we don't require exact match --
+        the user may have rotated keys since)
+
+    This 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 model.get("provider") != "custom":
+        return False
+    if model.get("base_url") != ctx.base_url:
+        return False
+    api_key = model.get("api_key")
+    if not isinstance(api_key, str) or not api_key.startswith("sk-substrate-"):
+        return False
+    return True
+
+
 class HermesAgent(Agent):
     name = "hermes"
     pretty_name = "Hermes"
@@ -216,19 +243,29 @@ class HermesAgent(Agent):
             return err
         assert payload is not None
 
-        # Refusal: marker absent AND user has a non-empty model: block we don't own.
-        if not _has_substrate_marker(payload) and _user_has_meaningful_model_block(payload):
-            notes.append(
-                "Hermes config.yaml has a user-owned `model:` block but no "
-                "substrate-setup marker; refused to overwrite. To take over, "
-                "delete the existing `model:` block (or its provider/api_key/"
-                "base_url keys) and re-run substrate-setup."
-            )
-            return AgentResult(
-                ResultStatus.ERROR,
-                "\n".join(notes),
-                tuple(backups),
-            )
+        # Marker absent: decide between auto-claim (shape already looks like
+        # ours — safe to take ownership) and refusal (truly user-owned).
+        if not _has_substrate_marker(payload):
+            existing_model = payload.get("model") or {}
+            if not isinstance(existing_model, dict):
+                existing_model = {}
+            if _user_has_meaningful_model_block(payload):
+                if _existing_matches_substrate_shape(existing_model, ctx):
+                    notes.append(
+                        "Hermes config.yaml had substrate-shaped keys but no "
+                        "marker; auto-claiming ownership."
+                    )
+                    # fall through to normal write (which adds the marker)
+                else:
+                    return AgentResult(
+                        ResultStatus.ERROR,
+                        "Hermes config.yaml has a user-owned `model:` block "
+                        "but no substrate-setup marker; refused to overwrite. "
+                        "To take over, delete the existing `model:` block "
+                        "(or its provider/api_key/base_url keys) and re-run "
+                        "substrate-setup.",
+                        tuple(backups),
+                    )
 
         if cfg_path.exists():
             backup = backup_once(cfg_path)

{substrate_setup-0.2.0 → substrate_setup-0.2.1}/substrate_setup/cli.py

@@ -103,12 +103,12 @@ def _run_per_agent(
 ) -> int:
     """Execute ``method`` on each detected agent. Print results. Return exit code."""
     if not quiet:
-        print(f"{label} agents …")
+        print(f"{label} agents ...")
         print("Detected agents:")
         for a in agents:
             detected = a.detect()
             tag = "[print-only handler]" if a.name == "cursor" else ""
-            mark = "✓" if detected else "·"
+            mark = "[ok]" if detected else "[--]"
             note = f"({detected})" if detected else "not installed"
             print(f"  {mark} {a.pretty_name:<12} {note} {tag}")
         print()
@@ -127,11 +127,11 @@ def _run_per_agent(
         if not quiet:
             prefix = f"{label} {a.pretty_name:<10}"
             if result.status == ResultStatus.ERROR:
-                print(f"{prefix} … ERROR: {result.message}")
+                print(f"{prefix} ... ERROR: {result.message}")
             elif result.status == ResultStatus.PRINT_ONLY:
-                print(f"{prefix} … printed walkthrough above.")
+                print(f"{prefix} ... printed walkthrough above.")
             else:
-                print(f"{prefix} … {result.message}")
+                print(f"{prefix} ... {result.message}")
             for backup in result.backup_paths:
                 print(f"             Backup: {backup}")
         if result.status == ResultStatus.ERROR:
@@ -164,6 +164,20 @@ def _build_ctx(
 
 
 def main(argv: list[str] | None = None) -> int:
+    # Safety net for non-ASCII stdout on Windows GBK-locale consoles
+    # (and any other narrow legacy encoding). Without this, printing a
+    # model id or error message that happens to contain a non-encodable
+    # glyph crashes the whole CLI with UnicodeEncodeError. We prefer
+    # UTF-8 with ``errors="replace"`` so a stray glyph degrades to ``?``
+    # rather than killing the run. ``reconfigure`` is only available on
+    # text streams that wrap a buffer — guard with ``hasattr``.
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            try:
+                stream.reconfigure(encoding="utf-8", errors="replace")
+            except (AttributeError, OSError):
+                pass
+
     parser = build_parser()
     args = parser.parse_args(argv)
 

{substrate_setup-0.2.0 → substrate_setup-0.2.1}/substrate_setup/credentials.py

@@ -76,7 +76,7 @@ def resolve_api_key(
         )
     if not KEY_REGEX.match(candidate):
         raise InvalidKeyFormatError(
-            "That doesn't look like a Substrate API key — expected "
+            "That doesn't look like a Substrate API key -- expected "
             "sk-substrate-... followed by at least 20 characters."
         )
     return candidate

{substrate_setup-0.2.0 → substrate_setup-0.2.1}/tests/agents/test_aider.py

@@ -92,6 +92,60 @@ def test_configure_preserves_user_aider_conf_keys(home_dir):
     assert conf_data["openai-api-base"] == "https://gw.example/v1"
 
 
+def test_auto_claim_when_shape_matches_unmarked(home_dir):
+    """If openai-api-base == ctx.base_url and openai-api-key starts with
+    sk-substrate- but the marker is absent, configure() should SUCCEED,
+    write the marker, and keep/refresh the keys. This is the
+    upgrade-from-0.1 / manually-fixed case; refusing here is friction
+    with no safety benefit.
+    """
+    (home_dir / ".aider.conf.yml").write_text(
+        "openai-api-base: https://gw.example/v1\n"
+        "openai-api-key: sk-substrate-prior-key-shaped-like-substrate\n"
+        "model: anthropic/claude-sonnet-4-6\n",
+        encoding="utf-8",
+    )
+    result = AiderAgent().configure(_ctx())
+    assert result.status == ResultStatus.SUCCESS
+
+    conf_data = _yaml().load(
+        (home_dir / ".aider.conf.yml").read_text(encoding="utf-8")
+    )
+    # Marker now present.
+    assert conf_data["_substrate_setup_managed_keys"] == [
+        "openai-api-base",
+        "openai-api-key",
+        "model",
+    ]
+    # Keys refreshed to ctx values.
+    assert conf_data["openai-api-base"] == "https://gw.example/v1"
+    assert conf_data["openai-api-key"] == VALID_KEY
+    assert conf_data["model"] == "anthropic/claude-sonnet-4-6"
+
+
+def test_still_refuses_truly_user_owned(home_dir):
+    """Marker absent + shape does NOT look substrate (api.openai.com
+    base_url, non-sk-substrate key) -> still ERROR + no write.
+    """
+    conf = home_dir / ".aider.conf.yml"
+    conf.write_text(
+        "openai-api-base: https://api.openai.com/v1\n"
+        "openai-api-key: sk-real-openai-key-not-substrate-shaped\n"
+        "model: openai/gpt-4o\n",
+        encoding="utf-8",
+    )
+    before = conf.read_bytes()
+
+    result = AiderAgent().configure(_ctx())
+    assert result.status == ResultStatus.ERROR
+    assert (
+        "user-owned" in result.message.lower()
+        or "refused" in result.message.lower()
+    )
+    # File untouched.
+    assert conf.read_bytes() == before
+
+
 def test_refuses_to_overwrite_user_keys_without_marker(home_dir):
     """If marker absent AND any of our 3 keys are user-set, refuse."""
     (home_dir / ".aider.conf.yml").write_text(

{substrate_setup-0.2.0 → substrate_setup-0.2.1}/tests/agents/test_hermes.py

@@ -179,6 +179,75 @@ _substrate_setup_managed_keys:
     assert payload["tools"]["enable_web_search"] is False
 
 
+def test_auto_claim_when_shape_matches_unmarked(home_dir):
+    """If model.* already looks substrate-shaped (provider=custom,
+    base_url == ctx.base_url, api_key startswith sk-substrate-) but the
+    marker is absent, configure() should SUCCEED, write the marker, and
+    keep/refresh the keys. This is the upgrade-from-0.1 / manually-fixed
+    case Frank hit; the prior refusal was UX friction with no safety
+    benefit (we'd be overwriting our own shape with our own shape).
+    """
+    hermes_dir = home_dir / ".hermes"
+    hermes_dir.mkdir()
+    # Substrate-shaped values, BUT no _substrate_setup_managed_keys marker.
+    (hermes_dir / "config.yaml").write_text(
+        """\
+model:
+  default: "anthropic/claude-sonnet-4-6"
+  provider: "custom"
+  api_key: "sk-substrate-prior-key-shaped-like-substrate"
+  base_url: "https://gw.example/v1"
+""",
+        encoding="utf-8",
+    )
+    result = HermesAgent().configure(_ctx())
+    assert result.status == ResultStatus.SUCCESS
+
+    payload = _yaml().load(
+        (hermes_dir / "config.yaml").read_text(encoding="utf-8")
+    )
+    # Marker now present.
+    assert payload["_substrate_setup_managed_keys"] == [
+        "model.default",
+        "model.provider",
+        "model.api_key",
+        "model.base_url",
+    ]
+    # Keys present (api_key refreshed to ctx.api_key).
+    model = payload["model"]
+    assert model["provider"] == "custom"
+    assert model["base_url"] == "https://gw.example/v1"
+    assert model["api_key"] == VALID_KEY
+    assert model["default"] == "anthropic/claude-sonnet-4-6"
+
+
+def test_still_refuses_truly_user_owned(home_dir):
+    """Marker absent + shape does NOT look substrate (openai provider,
+    api.openai.com base_url, non-sk-substrate key) -> still ERROR + no
+    write. Belt-and-suspenders for the auto-claim split.
+    """
+    hermes_dir = home_dir / ".hermes"
+    hermes_dir.mkdir()
+    cfg = hermes_dir / "config.yaml"
+    cfg.write_text(
+        """\
+model:
+  default: "gpt-4o"
+  provider: "openai"
+  api_key: "sk-real-openai-key-not-substrate-shaped"
+  base_url: "https://api.openai.com/v1"
+""",
+        encoding="utf-8",
+    )
+    before = cfg.read_bytes()
+
+    result = HermesAgent().configure(_ctx())
+    assert result.status == ResultStatus.ERROR
+    assert "user-owned" in result.message.lower() or "refused" in result.message.lower()
+    # File untouched.
+    assert cfg.read_bytes() == before
+
+
 def test_refuses_to_overwrite_user_model_without_marker(home_dir):
     """If marker absent AND model.provider is user-set non-substrate value, refuse."""
     hermes_dir = home_dir / ".hermes"

{substrate_setup-0.2.0 → substrate_setup-0.2.1}/tests/test_cli.py

@@ -102,6 +102,63 @@ def test_agents_only_filters(stub_env, httpx_mock, capsys, monkeypatch):
     assert code == EXIT_OK
 
 
+def test_main_reconfigures_stdout_utf8_errors_replace(monkeypatch):
+    """main() must call ``reconfigure(encoding='utf-8', errors='replace')`` on
+    stdout/stderr at entry — without this, printing any non-ASCII glyph
+    (e.g. a model id or upstream error message) crashes on Windows GBK
+    consoles with UnicodeEncodeError. Affects every China beta user.
+    """
+    import sys as _sys
+
+    captured: list[tuple[str, dict[str, object]]] = []
+
+    class _FakeStream:
+        def reconfigure(self, **kwargs: object) -> None:
+            captured.append(("reconfigure", kwargs))
+
+        def write(self, _data: str) -> int:
+            return 0
+
+        def flush(self) -> None:
+            pass
+
+    fake_out = _FakeStream()
+    fake_err = _FakeStream()
+    monkeypatch.setattr(_sys, "stdout", fake_out)
+    monkeypatch.setattr(_sys, "stderr", fake_err)
+
+    # ``version`` is the cheapest path — it doesn't touch HTTP or files.
+    main(["version"])
+
+    # Both streams must have been reconfigured with utf-8 + errors=replace.
+    kwargs_seen = [c[1] for c in captured if c[0] == "reconfigure"]
+    assert len(kwargs_seen) == 2, f"expected 2 reconfigure calls, got {captured}"
+    for kw in kwargs_seen:
+        assert kw == {"encoding": "utf-8", "errors": "replace"}, kw
+
+
+def test_status_glyphs_are_ascii_only(stub_env, httpx_mock, capsys):
+    """The detected/not-installed status line must not print any non-ASCII
+    char (the old ``✓``/``·`` glyphs and ``…`` ellipsis crashed GBK consoles).
+    """
+    httpx_mock.add_response(
+        url="https://gw.example/v1/models",
+        json={"object": "list", "data": [
+            {"id": "openai/gpt-5.5", "object": "model", "owned_by": "openai",
+             "display_name": "GPT-5.5", "description": "x"},
+        ]},
+    )
+    code = main(["configure", "--base-url", "https://gw.example"])
+    assert code == EXIT_OK
+    out = capsys.readouterr().out
+    # The whole orchestrator output must be ASCII-clean now.
+    non_ascii = [ch for ch in out if ord(ch) > 127]
+    assert not non_ascii, (
+        f"non-ASCII chars leaked into CLI output: "
+        f"{sorted(set(non_ascii))!r}"
+    )
+
+
 def test_dry_run_does_not_write(stub_env, httpx_mock, capsys):
     httpx_mock.add_response(
         url="https://gw.example/v1/models",

{substrate_setup-0.2.0 → substrate_setup-0.2.1}/uv.lock

@@ -305,7 +305,7 @@ wheels = [
 
 [[package]]
 name = "substrate-setup"
-version = "0.2.0"
+version = "0.2.1"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },