substrate-setup 0.1.0__py3-none-any.whl

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/__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/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/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/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: ...

substrate_setup/agents/continue_dev.py

@@ -0,0 +1,194 @@
+"""Continue (VS Code / JetBrains extension) integration.
+
+Files (current default is YAML, JSON is deprecated):
+  ~/.continue/config.yaml — preferred
+  ~/.continue/config.json — legacy fallback; ignored by Continue if YAML present
+"""
+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.catalog import CatalogEntry
+from substrate_setup.markers import MARKER_KEY, MARKER_VALUE, is_substrate_managed
+
+
+def _dir() -> Path:
+    return Path.home() / ".continue"
+
+
+def _yaml_path() -> Path:
+    return _dir() / "config.yaml"
+
+
+def _json_path() -> Path:
+    return _dir() / "config.json"
+
+
+def _yaml() -> YAML:
+    y = YAML()
+    y.preserve_quotes = True
+    y.indent(mapping=2, sequence=4, offset=2)
+    return y
+
+
+def _model_entry(ctx: ConfigureContext, catalog_id: str, display: str) -> dict[str, Any]:
+    return {
+        "name": display,
+        "provider": "openai",   # documented form for custom OpenAI-compat gateways
+        "model": catalog_id,
+        "apiBase": ctx.base_url,
+        "apiKey": ctx.api_key,
+        "roles": ["chat", "edit", "apply"],
+        MARKER_KEY: MARKER_VALUE,
+    }
+
+
+def _choose_path() -> tuple[Path, str]:
+    """Return (path, format-tag) where format-tag is 'yaml' or 'json'."""
+    if _yaml_path().exists():
+        return _yaml_path(), "yaml"
+    if _json_path().exists():
+        return _json_path(), "json"
+    return _yaml_path(), "yaml"
+
+
+def _load(path: Path, fmt: str) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    text = path.read_text(encoding="utf-8")
+    if fmt == "yaml":
+        result: dict[str, Any] = _yaml().load(text) or {}
+        return result
+    result = json.loads(text)
+    return result
+
+
+def _dump(path: Path, fmt: str, data: dict[str, Any]) -> None:
+    if fmt == "yaml":
+        buf = io.StringIO()
+        _yaml().dump(data, buf)
+        path.write_text(buf.getvalue(), encoding="utf-8")
+    else:
+        path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+
+
+def _merge_models(
+    existing: list[dict[str, Any]],
+    catalog: list[CatalogEntry],
+    ctx: ConfigureContext,
+) -> list[dict[str, Any]]:
+    """Merge with marker-respecting semantics.
+
+    - Preserve user-authored entries (no marker).
+    - Replace substrate-managed entries to match the current catalog (live path).
+    - On fallback path, keep existing substrate-managed entries even if not in catalog.
+    """
+    user_entries = [e for e in existing if not is_substrate_managed(e)]
+    existing_substrate_ids = {
+        e.get("model") for e in existing if is_substrate_managed(e)
+    }
+    catalog_ids = {entry.id for entry in catalog}
+
+    fresh_entries = [
+        _model_entry(ctx, entry.id, entry.display_name) for entry in catalog
+    ]
+
+    if ctx.catalog_source == "fallback":
+        kept_ids = existing_substrate_ids - catalog_ids
+        for old in existing:
+            if is_substrate_managed(old) and old.get("model") in kept_ids:
+                fresh_entries.append(old)
+
+    return user_entries + fresh_entries
+
+
+class ContinueAgent(Agent):
+    name = "continue"
+    pretty_name = "Continue"
+
+    def detect(self) -> Path | None:
+        if _yaml_path().exists():
+            return _yaml_path()
+        if _json_path().exists():
+            return _json_path()
+        return None
+
+    def configure(self, ctx: ConfigureContext) -> AgentResult:
+        _dir().mkdir(parents=True, exist_ok=True)
+        path, fmt = _choose_path()
+        backups: list[Path] = []
+
+        if path.exists():
+            backup = backup_once(path)
+            if backup is not None:
+                backups.append(backup)
+
+        payload = _load(path, fmt)
+        existing_models = payload.get("models") or []
+        merged = _merge_models(existing_models, ctx.catalog, ctx)
+        payload["models"] = merged
+
+        notes: list[str] = []
+        if fmt == "json":
+            notes.append(
+                "Continue: editing legacy config.json (consider migrating to config.yaml)."
+            )
+            print(notes[-1])
+
+        if not ctx.dry_run:
+            _dump(path, fmt, payload)
+
+        msg = f"{len(ctx.catalog)} models written, API base + key set in {path}."
+        return AgentResult(ResultStatus.SUCCESS, msg, tuple(backups))
+
+    def verify(self, ctx: ConfigureContext) -> AgentResult:
+        path = self.detect()
+        if path is None:
+            return AgentResult(ResultStatus.ERROR, "Continue config not present")
+        fmt = "yaml" if path.suffix == ".yaml" else "json"
+        payload = _load(path, fmt)
+        substrate_ids = {
+            m.get("model") for m in (payload.get("models") or [])
+            if is_substrate_managed(m)
+        }
+        catalog_ids = {e.id for e in ctx.catalog}
+        missing = catalog_ids - substrate_ids
+        stale = substrate_ids - catalog_ids
+        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:
+        path = self.detect()
+        if path is None:
+            return AgentResult(ResultStatus.SKIPPED, "Continue not installed")
+        fmt = "yaml" if path.suffix == ".yaml" else "json"
+        backup = backup_once(path)
+        payload = _load(path, fmt)
+        payload["models"] = [
+            m for m in (payload.get("models") or []) if not is_substrate_managed(m)
+        ]
+        if not ctx.dry_run:
+            _dump(path, fmt, payload)
+        return AgentResult(
+            ResultStatus.SUCCESS,
+            "Removed substrate model entries from Continue",
+            (backup,) if backup else (),
+        )

substrate_setup/agents/cursor.py

@@ -0,0 +1,90 @@
+"""Cursor handler — print-only.
+
+Cursor stores its custom OpenAI base URL + key + model list in
+state.vscdb (SQLite) + OS secure storage. It does NOT read these from
+settings.json and does NOT read OPENAI_API_KEY from env. So this
+handler can only print a walkthrough.
+"""
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+from substrate_setup.agents.base import (
+    Agent,
+    AgentResult,
+    ConfigureContext,
+    ResultStatus,
+)
+
+
+def _user_data_candidates() -> list[Path]:
+    home = Path.home()
+    candidates = [
+        home / "Library/Application Support/Cursor",
+        home / ".config/Cursor",
+    ]
+    if sys.platform == "win32":
+        appdata = os.environ.get("APPDATA")
+        if appdata:
+            candidates.append(Path(appdata) / "Cursor")
+    return candidates
+
+
+class CursorAgent(Agent):
+    name = "cursor"
+    pretty_name = "Cursor"
+
+    def detect(self) -> Path | None:
+        for path in _user_data_candidates():
+            if path.exists():
+                return path
+        return None
+
+    def configure(self, ctx: ConfigureContext) -> AgentResult:
+        bullets = "\n".join(f"     - {e.id}" for e in ctx.catalog)
+        print(
+            "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"
+            "  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"
+            f"{bullets}\n"
+            "\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."
+        )
+        return AgentResult(
+            ResultStatus.PRINT_ONLY,
+            "Printed paste-into-Cursor walkthrough",
+        )
+
+    def verify(self, ctx: ConfigureContext) -> AgentResult:
+        print(
+            "Cursor: cannot verify automatically — config lives in Cursor's secure storage."
+        )
+        return AgentResult(
+            ResultStatus.PRINT_ONLY,
+            "Cursor verify is print-only",
+        )
+
+    def remove(self, ctx: ConfigureContext) -> AgentResult:
+        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"
+            "  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."
+        )
+        return AgentResult(
+            ResultStatus.PRINT_ONLY,
+            "Printed remove-from-Cursor walkthrough",
+        )