substrate-setup 0.1.0__tar.gz

substrate_setup-0.1.0/.gitignore

@@ -0,0 +1,71 @@
+# 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/
+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

substrate_setup-0.1.0/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: substrate-setup
+Version: 0.1.0
+Summary: One-shot local configurator for coding agents against a Substrate gateway
+Author: Substrate Solutions
+License: MIT
+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.
+
+```bash
+pip install substrate-setup
+export SUBSTRATE_API_KEY="sk-substrate-..."  # or be prompted
+python -m substrate_setup
+```
+
+Run `python -m substrate_setup --help` for subcommands (`configure`, `verify`, `remove`).

substrate_setup-0.1.0/README.md

@@ -0,0 +1,11 @@
+# substrate-setup
+
+One-shot configurator that points local coding agents at a Substrate gateway.
+
+```bash
+pip install substrate-setup
+export SUBSTRATE_API_KEY="sk-substrate-..."  # or be prompted
+python -m substrate_setup
+```
+
+Run `python -m substrate_setup --help` for subcommands (`configure`, `verify`, `remove`).

substrate_setup-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "substrate-setup"
+version = "0.1.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" }
+dependencies = [
+  "httpx>=0.27",
+  "ruamel.yaml>=0.18",
+]
+
+[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.1.0/scripts/lint_no_app_import.sh

@@ -0,0 +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/"

substrate_setup-0.1.0/scripts/regenerate_fallback_catalog.py

@@ -0,0 +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())

substrate_setup-0.1.0/substrate_setup/__init__.py

@@ -0,0 +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.1.0"

substrate_setup-0.1.0/substrate_setup/__main__.py

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

substrate_setup-0.1.0/substrate_setup/agents/__init__.py

@@ -0,0 +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]

substrate_setup-0.1.0/substrate_setup/agents/aider.py

@@ -0,0 +1,250 @@
+"""Aider integration.
+
+Files:
+  ~/.aider.conf.yml             — openai-api-base + model-metadata-file pointer
+  ~/.aider.model.metadata.json  — LiteLLM-shaped per-model metadata
+  ~/.env                        — OPENAI_API_KEY
+
+NEVER touches project-local .aider.conf.yml, .aider.model.metadata.json,
+or .env files.
+"""
+from __future__ import annotations
+
+import io
+import json
+from pathlib import Path
+from typing import Any
+
+from ruamel.yaml import YAML
+
+from substrate_setup.agents.base import (
+    Agent,
+    AgentResult,
+    ConfigureContext,
+    ResultStatus,
+)
+from substrate_setup.backup import backup_once
+from substrate_setup.markers import MARKER_KEY, MARKER_VALUE, is_substrate_managed
+
+OPENAI_KEY_VAR = "OPENAI_API_KEY"
+
+
+def _conf_path() -> Path:
+    return Path.home() / ".aider.conf.yml"
+
+
+def _meta_path() -> Path:
+    return Path.home() / ".aider.model.metadata.json"
+
+
+def _env_path() -> Path:
+    return Path.home() / ".env"
+
+
+def _yaml() -> YAML:
+    y = YAML()
+    y.preserve_quotes = True
+    y.indent(mapping=2, sequence=4, offset=2)
+    return y
+
+
+def _load_yaml(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    result: dict[str, Any] = _yaml().load(path.read_text(encoding="utf-8")) or {}
+    return result
+
+
+def _dump_yaml(path: Path, data: dict[str, Any]) -> None:
+    buf = io.StringIO()
+    _yaml().dump(data, buf)
+    path.write_text(buf.getvalue(), encoding="utf-8")
+
+
+def _load_meta(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    result: dict[str, Any] = json.loads(path.read_text(encoding="utf-8"))
+    return result
+
+
+def _dump_meta(path: Path, data: dict[str, Any]) -> None:
+    path.write_text(json.dumps(data, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+
+def _model_id_for_aider(catalog_id: str) -> str:
+    """LiteLLM needs `openai/` prefix to route through OPENAI_API_BASE."""
+    return f"openai/{catalog_id}"
+
+
+def _metadata_for_entry() -> dict[str, Any]:
+    return {
+        "max_input_tokens": 200000,
+        "max_output_tokens": 8192,
+        "input_cost_per_token": 0.0,   # Cost tracking lives in the gateway, not in Aider.
+        "output_cost_per_token": 0.0,
+        "litellm_provider": "openai",
+        "mode": "chat",
+        MARKER_KEY: MARKER_VALUE,
+    }
+
+
+def _read_env_lines(path: Path) -> list[str]:
+    if not path.exists():
+        return []
+    return path.read_text(encoding="utf-8").splitlines()
+
+
+def _write_env_lines(path: Path, lines: list[str]) -> None:
+    path.write_text("\n".join(lines) + ("\n" if lines else ""), encoding="utf-8")
+
+
+class AiderAgent(Agent):
+    name = "aider"
+    pretty_name = "Aider"
+
+    def detect(self) -> Path | None:
+        conf = _conf_path()
+        return conf if conf.exists() else None
+
+    def configure(self, ctx: ConfigureContext) -> AgentResult:
+        backups: list[Path] = []
+        notes: list[str] = []
+
+        # ── ~/.aider.conf.yml ────────────────────────────────────────
+        conf = _conf_path()
+        if conf.exists():
+            backup = backup_once(conf)
+            if backup is not None:
+                backups.append(backup)
+        conf_data = _load_yaml(conf)
+        conf_data["openai-api-base"] = ctx.base_url
+        conf_data["model-metadata-file"] = str(_meta_path())
+        if not ctx.dry_run:
+            _dump_yaml(conf, conf_data)
+
+        # ── ~/.aider.model.metadata.json ─────────────────────────────
+        meta = _meta_path()
+        if meta.exists():
+            backup = backup_once(meta)
+            if backup is not None:
+                backups.append(backup)
+        meta_data = _load_meta(meta)
+        catalog_keys = {_model_id_for_aider(e.id) for e in ctx.catalog}
+
+        # Drop substrate-managed entries that are no longer in the live catalog.
+        if ctx.catalog_source == "live":
+            meta_data = {
+                k: v for k, v in meta_data.items()
+                if not is_substrate_managed(v) or k in catalog_keys
+            }
+        # Add / update from current catalog.
+        for entry in ctx.catalog:
+            meta_data[_model_id_for_aider(entry.id)] = _metadata_for_entry()
+
+        if not ctx.dry_run:
+            _dump_meta(meta, meta_data)
+
+        # ── ~/.env (credential) ──────────────────────────────────────
+        env = _env_path()
+        lines = _read_env_lines(env)
+        existing_value = None
+        for line in lines:
+            if line.startswith(f"{OPENAI_KEY_VAR}="):
+                existing_value = line.split("=", 1)[1]
+                break
+        should_write_env = False
+        new_lines = list(lines)
+        if existing_value is None:
+            new_lines.append(f"{OPENAI_KEY_VAR}={ctx.api_key}")
+            should_write_env = True
+        elif existing_value.startswith("sk-substrate-"):
+            if existing_value != ctx.api_key:
+                new_lines = [
+                    f"{OPENAI_KEY_VAR}={ctx.api_key}"
+                    if line.startswith(f"{OPENAI_KEY_VAR}=")
+                    else line
+                    for line in lines
+                ]
+                should_write_env = True
+        else:
+            notes.append(
+                "Aider's ~/.env already has OPENAI_API_KEY set to a non-Substrate-shaped "
+                "value; please update manually."
+            )
+
+        if should_write_env:
+            if env.exists():
+                env_backup = backup_once(env)
+                if env_backup is not None:
+                    backups.append(env_backup)
+            if not ctx.dry_run:
+                _write_env_lines(env, new_lines)
+
+        msg = (
+            f"{len(ctx.catalog)} models written. Conf: ~/.aider.conf.yml, "
+            "metadata: ~/.aider.model.metadata.json, key in ~/.env."
+        )
+        if notes:
+            msg += "\n" + "\n".join(notes)
+        return AgentResult(ResultStatus.SUCCESS, msg, tuple(backups))
+
+    def verify(self, ctx: ConfigureContext) -> AgentResult:
+        meta = _meta_path()
+        if not meta.exists():
+            return AgentResult(ResultStatus.ERROR, "Aider metadata file does not exist")
+        meta_data = _load_meta(meta)
+        catalog_keys = {_model_id_for_aider(e.id) for e in ctx.catalog}
+        substrate_keys = {
+            k for k, v in meta_data.items() if is_substrate_managed(v)
+        }
+        missing = catalog_keys - substrate_keys
+        stale = substrate_keys - catalog_keys
+        if missing or stale:
+            parts = []
+            if missing:
+                parts.append(f"missing: {sorted(missing)}")
+            if stale:
+                parts.append(f"stale: {sorted(stale)}")
+            return AgentResult(ResultStatus.ERROR, "; ".join(parts))
+        return AgentResult(ResultStatus.SUCCESS, "in sync")
+
+    def remove(self, ctx: ConfigureContext) -> AgentResult:
+        meta = _meta_path()
+        backups: list[Path] = []
+        if meta.exists():
+            backup = backup_once(meta)
+            if backup is not None:
+                backups.append(backup)
+            meta_data = _load_meta(meta)
+            meta_data = {
+                k: v for k, v in meta_data.items() if not is_substrate_managed(v)
+            }
+            if not ctx.dry_run:
+                _dump_meta(meta, meta_data)
+
+        # Strip OPENAI_API_KEY from ~/.env only if its value is currently a Substrate key.
+        env = _env_path()
+        if env.exists():
+            lines = _read_env_lines(env)
+            kept = []
+            stripped = False
+            for line in lines:
+                if line.startswith(f"{OPENAI_KEY_VAR}="):
+                    value = line.split("=", 1)[1]
+                    if value.startswith("sk-substrate-"):
+                        stripped = True
+                        continue
+                kept.append(line)
+            if stripped:
+                env_backup = backup_once(env)
+                if env_backup is not None:
+                    backups.append(env_backup)
+                if not ctx.dry_run:
+                    _write_env_lines(env, kept)
+
+        return AgentResult(
+            ResultStatus.SUCCESS,
+            "Removed substrate metadata entries from Aider",
+            tuple(backups),
+        )

substrate_setup-0.1.0/substrate_setup/agents/base.py

@@ -0,0 +1,56 @@
+"""Abstract base class + result type for agent handlers.
+
+All agent handlers (hermes, cursor, aider, continue_dev) implement this
+interface. The orchestrator in cli.py treats them polymorphically.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from enum import StrEnum
+from pathlib import Path
+
+from substrate_setup.catalog import CatalogEntry
+
+
+class ResultStatus(StrEnum):
+    SUCCESS = "success"
+    ERROR = "error"
+    SKIPPED = "skipped"          # agent not installed
+    PRINT_ONLY = "print_only"    # for Cursor — handled, but no file write
+
+
+@dataclass(frozen=True)
+class AgentResult:
+    status: ResultStatus
+    message: str
+    backup_paths: tuple[Path, ...] = field(default_factory=tuple)
+
+
+@dataclass(frozen=True)
+class ConfigureContext:
+    base_url: str
+    api_key: str
+    catalog: list[CatalogEntry]
+    catalog_source: str            # "live" or "fallback"
+    dry_run: bool
+
+
+class Agent(ABC):
+    """Each coding-agent integration implements this."""
+
+    name: str                       # short id, e.g. "cursor"
+    pretty_name: str                # display name, e.g. "Cursor"
+
+    @abstractmethod
+    def detect(self) -> Path | None:
+        """Return the primary path the agent would touch, or None if not installed."""
+
+    @abstractmethod
+    def configure(self, ctx: ConfigureContext) -> AgentResult: ...
+
+    @abstractmethod
+    def verify(self, ctx: ConfigureContext) -> AgentResult: ...
+
+    @abstractmethod
+    def remove(self, ctx: ConfigureContext) -> AgentResult: ...