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

{substrate_setup-0.1.0 → substrate_setup-0.2.1}/.gitignore

@@ -28,6 +28,9 @@ node_modules/
 .next/
 .vercel/
 .turbo/
+
+# CodeGraph (local-only code knowledge graph index)
+.codegraph/
 out/
 *.tsbuildinfo
 .npm/

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

@@ -1,9 +1,22 @@
 Metadata-Version: 2.4
 Name: substrate-setup
-Version: 0.1.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
+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

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

@@ -4,17 +4,34 @@ build-backend = "hatchling.build"
 
 [project]
 name = "substrate-setup"
-version = "0.1.0"
+version = "0.2.1"
 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",

{substrate_setup-0.1.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.1.0"
+__version__ = "0.2.1"

substrate_setup-0.2.1/substrate_setup/agents/aider.py

@@ -0,0 +1,316 @@
+"""Aider integration (0.2.0 — single conf.yml, no metadata file).
+
+Files:
+  ~/.aider.conf.yml — openai-api-base, openai-api-key, model (default)
+
+Why no `.aider.model.metadata.json` (was written by 0.1)
+-------------------------------------------------------
+Aider routes everything through one OpenAI-compatible endpoint set via
+``openai-api-base``. Per-model LiteLLM metadata (context length, cost
+per token) lives upstream on the gateway, not in Aider; the metadata
+file was over-engineered. 0.2.0 drops it. A user who wants a specific
+model passes ``--model <id>`` on the Aider CLI; otherwise the ``model:``
+key in ``~/.aider.conf.yml`` is used.
+
+Why no `~/.env` (was written by 0.1)
+------------------------------------
+Aider's docs say the inline ``openai-api-key`` in ``~/.aider.conf.yml``
+is the supported way to authenticate against OpenAI-compatible
+gateways. Writing a shared ``~/.env`` was an over-reach that risked
+clobbering other tools' OPENAI_API_KEY. 0.2.0 drops the env write.
+``remove()`` still cleans up a legacy ``~/.aider.model.metadata.json``
+and a substrate-shaped ``OPENAI_API_KEY=`` line in ``~/.env`` if they
+were planted by 0.1.
+
+Marker discipline
+-----------------
+Since the keys we own (``openai-api-base``, ``openai-api-key``,
+``model``) sit at the top level of a user-shared YAML doc, we write
+a sibling marker:
+
+    _substrate_setup_managed_keys:
+      - "openai-api-base"
+      - "openai-api-key"
+      - "model"
+
+If the marker is absent AND any of those three keys are user-set,
+configure()/remove() refuses to touch them.
+"""
+from __future__ import annotations
+
+import io
+import os
+import sys
+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
+
+MANAGED_KEYS_MARKER = "_substrate_setup_managed_keys"
+MANAGED_KEYS: list[str] = ["openai-api-base", "openai-api-key", "model"]
+
+
+def _conf_path() -> Path:
+    return Path.home() / ".aider.conf.yml"
+
+
+def _legacy_meta_path() -> Path:
+    return Path.home() / ".aider.model.metadata.json"
+
+
+def _legacy_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] | None = _yaml().load(path.read_text(encoding="utf-8"))
+    return result or {}
+
+
+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")
+    _restrict_file_mode(path)
+
+
+def _restrict_file_mode(path: Path) -> None:
+    """0600 on POSIX so the inline ``openai-api-key`` isn't world-readable.
+
+    No-op on Windows (file mode bits aren't POSIX-ish there; ACLs already
+    default to per-user under %USERPROFILE%).
+    """
+    if sys.platform == "win32":
+        return
+    try:
+        os.chmod(path, 0o600)
+    except OSError:
+        pass
+
+
+def _has_substrate_marker(payload: dict[str, Any]) -> bool:
+    marker = payload.get(MANAGED_KEYS_MARKER)
+    if not isinstance(marker, list):
+        return False
+    return set(MANAGED_KEYS).issubset(set(marker))
+
+
+def _user_has_meaningful_keys(payload: dict[str, Any]) -> bool:
+    for k in MANAGED_KEYS:
+        v = payload.get(k)
+        if isinstance(v, str) and v.strip():
+            return True
+    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")
+    return str(catalog[0].id)
+
+
+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:
+        conf = _conf_path()
+        backups: list[Path] = []
+        payload = _load_yaml(conf)
+
+        if not _has_substrate_marker(payload) and _user_has_meaningful_keys(payload):
+            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)
+            if backup is not None:
+                backups.append(backup)
+
+        payload["openai-api-base"] = ctx.base_url
+        payload["openai-api-key"] = ctx.api_key
+        payload["model"] = _pick_default_model(ctx.catalog)
+        payload[MANAGED_KEYS_MARKER] = list(MANAGED_KEYS)
+
+        if not ctx.dry_run:
+            _dump_yaml(conf, payload)
+
+        return AgentResult(
+            ResultStatus.SUCCESS,
+            f"Wrote openai-api-base + openai-api-key + model into {conf}.",
+            tuple(backups),
+        )
+
+    def verify(self, ctx: ConfigureContext) -> AgentResult:
+        conf = _conf_path()
+        if not conf.exists():
+            return AgentResult(ResultStatus.ERROR, "Aider conf.yml does not exist")
+        payload = _load_yaml(conf)
+        if not _has_substrate_marker(payload):
+            return AgentResult(
+                ResultStatus.ERROR,
+                "Aider ~/.aider.conf.yml is not managed by substrate-setup "
+                "(marker missing)",
+            )
+
+        problems: list[str] = []
+        if payload.get("openai-api-base") != ctx.base_url:
+            problems.append(
+                f"openai-api-base: expected {ctx.base_url!r}, "
+                f"got {payload.get('openai-api-base')!r}"
+            )
+        expected_model = _pick_default_model(ctx.catalog)
+        if payload.get("model") != expected_model:
+            problems.append(
+                f"model: expected {expected_model!r}, got {payload.get('model')!r}"
+            )
+        api_key = payload.get("openai-api-key")
+        if not isinstance(api_key, str) or len(api_key) < 20:
+            problems.append("openai-api-key: missing or implausibly short")
+
+        if problems:
+            return AgentResult(ResultStatus.ERROR, "; ".join(problems))
+        return AgentResult(ResultStatus.SUCCESS, "in sync")
+
+    def remove(self, ctx: ConfigureContext) -> AgentResult:
+        conf = _conf_path()
+        if not conf.exists():
+            # Still try to clean up legacy artifacts even if conf.yml is gone.
+            cleaned_legacy = self._clean_legacy(ctx)
+            if cleaned_legacy:
+                return AgentResult(
+                    ResultStatus.SUCCESS,
+                    "Removed legacy Aider artifacts (~/.aider.model.metadata.json / ~/.env)",
+                    (),
+                )
+            return AgentResult(ResultStatus.SKIPPED, "Aider not configured")
+
+        payload = _load_yaml(conf)
+        if not _has_substrate_marker(payload):
+            return AgentResult(
+                ResultStatus.SKIPPED,
+                "Aider ~/.aider.conf.yml is not managed by substrate-setup; "
+                "refusing to delete keys we don't own",
+            )
+
+        backups: list[Path] = []
+        backup = backup_once(conf)
+        if backup is not None:
+            backups.append(backup)
+
+        for k in MANAGED_KEYS:
+            payload.pop(k, None)
+        payload.pop(MANAGED_KEYS_MARKER, None)
+
+        if not ctx.dry_run:
+            _dump_yaml(conf, payload)
+
+        # Also clean up legacy artifacts written by 0.1 (best-effort).
+        self._clean_legacy(ctx, backups=backups)
+
+        return AgentResult(
+            ResultStatus.SUCCESS,
+            f"Removed substrate-managed keys from {conf}",
+            tuple(backups),
+        )
+
+    @staticmethod
+    def _clean_legacy(
+        ctx: ConfigureContext, *, backups: list[Path] | None = None
+    ) -> bool:
+        """Delete 0.1 artifacts: ~/.aider.model.metadata.json and substrate
+        entries in ~/.env. Returns True if anything was cleaned."""
+        if backups is None:
+            backups = []
+        did_something = False
+
+        # ~/.aider.model.metadata.json
+        legacy_meta = _legacy_meta_path()
+        if legacy_meta.exists():
+            backup = backup_once(legacy_meta)
+            if backup is not None:
+                backups.append(backup)
+            if not ctx.dry_run:
+                legacy_meta.unlink()
+            did_something = True
+
+        # ~/.env: strip the OPENAI_API_KEY line if its value starts with "sk-substrate-".
+        legacy_env = _legacy_env_path()
+        if legacy_env.exists():
+            lines = legacy_env.read_text(encoding="utf-8").splitlines()
+            kept: list[str] = []
+            stripped = False
+            for line in lines:
+                if line.startswith("OPENAI_API_KEY="):
+                    value = line.split("=", 1)[1]
+                    if value.startswith("sk-substrate-"):
+                        stripped = True
+                        continue
+                kept.append(line)
+            if stripped:
+                backup = backup_once(legacy_env)
+                if backup is not None:
+                    backups.append(backup)
+                if not ctx.dry_run:
+                    legacy_env.write_text(
+                        "\n".join(kept) + ("\n" if kept else ""), encoding="utf-8"
+                    )
+                did_something = True
+
+        return did_something

substrate_setup-0.2.1/substrate_setup/agents/continue_dev.py

@@ -0,0 +1,278 @@
+"""Continue (VS Code / JetBrains extension) integration.
+
+0.2.0 writes only ``~/.continue/config.yaml``. The legacy
+``~/.continue/config.json`` is migrated: if it exists but config.yaml
+doesn't, we read the JSON, copy the user's ``models`` array over, back
+up the JSON to ``config.json.substrate-bak-<ts>``, and write fresh YAML.
+
+Fresh config.yaml carries the required top-level fields the Continue
+upstream config schema needs:
+
+  name: substrate-setup
+  version: 0.0.1
+  schema: v1
+  models: [...]
+
+Each substrate-managed model entry:
+
+  - name: "<model_id>"
+    provider: openai
+    apiBase: "<base_url>"
+    apiKey: "<api_key>"
+    model: "<model_id>"
+    roles: [chat, edit, apply, summarize]
+    _substrate_managed: true
+
+The ``_substrate_managed: true`` marker is per-entry (Continue's
+``models`` is a list of dicts, so each dict can carry its own marker
+without colliding with user state).
+"""
+from __future__ import annotations
+
+import io
+import json
+import os
+import sys
+import time
+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
+
+CONFIG_NAME = "substrate-setup"
+CONFIG_VERSION = "0.0.1"
+CONFIG_SCHEMA = "v1"
+DEFAULT_ROLES = ["chat", "edit", "apply", "summarize"]
+
+
+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 _load_yaml(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    result: dict[str, Any] | None = _yaml().load(path.read_text(encoding="utf-8"))
+    return result or {}
+
+
+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")
+    _restrict_file_mode(path)
+
+
+def _restrict_file_mode(path: Path) -> None:
+    """0600 on POSIX so per-model inline ``apiKey`` values aren't world-readable.
+
+    No-op on Windows (file mode bits aren't POSIX-ish there; ACLs already
+    default to per-user under %USERPROFILE%).
+    """
+    if sys.platform == "win32":
+        return
+    try:
+        os.chmod(path, 0o600)
+    except OSError:
+        pass
+
+
+def _load_json(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 _model_entry(ctx: ConfigureContext, catalog_id: str) -> dict[str, Any]:
+    return {
+        "name": catalog_id,
+        "provider": "openai",   # OpenAI-compatible gateway
+        "model": catalog_id,
+        "apiBase": ctx.base_url,
+        "apiKey": ctx.api_key,
+        "roles": list(DEFAULT_ROLES),
+        MARKER_KEY: MARKER_VALUE,
+    }
+
+
+def _merge_models(
+    existing: list[dict[str, Any]],
+    catalog: list[CatalogEntry],
+    ctx: ConfigureContext,
+) -> list[dict[str, Any]]:
+    """Marker-respecting merge.
+
+    - 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 absent
+      from the (potentially stale) 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) 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
+
+
+def _ensure_required_top_level(payload: dict[str, Any]) -> dict[str, Any]:
+    """Make sure name/version/schema are set; populate from defaults if missing."""
+    payload.setdefault("name", CONFIG_NAME)
+    payload.setdefault("version", CONFIG_VERSION)
+    payload.setdefault("schema", CONFIG_SCHEMA)
+    return payload
+
+
+def _migrate_legacy_json(json_path: Path, yaml_path: Path) -> list[Path]:
+    """Migrate config.json → config.yaml. Returns the list of backup paths created.
+
+    Strategy:
+      - Read JSON.
+      - Copy its ``models`` array (and any other top-level keys) onto a fresh
+        YAML payload with the required ``name``/``version``/``schema`` fields.
+      - Write YAML.
+      - Backup JSON to ``config.json.substrate-bak-<ts>``.
+    """
+    backups: list[Path] = []
+    legacy = _load_json(json_path)
+
+    # Carry over the user's data wholesale. We'll fill in required fields below.
+    yaml_payload: dict[str, Any] = dict(legacy)
+    _ensure_required_top_level(yaml_payload)
+    yaml_payload.setdefault("models", [])
+    # Leave a breadcrumb so future readers know what happened.
+    yaml_payload["_substrate_migration_note"] = (
+        "migrated from config.json by substrate-setup"
+    )
+
+    # Back up the legacy file. Use a stable suffix so detect/cleanup logic can
+    # find it if needed.
+    ts = int(time.time())
+    backup_path = json_path.parent / f"{json_path.name}.substrate-bak-{ts}"
+    backup_path.write_text(json_path.read_text(encoding="utf-8"), encoding="utf-8")
+    backups.append(backup_path)
+
+    yaml_path.parent.mkdir(parents=True, exist_ok=True)
+    _dump_yaml(yaml_path, yaml_payload)
+
+    return backups
+
+
+class ContinueAgent(Agent):
+    name = "continue"
+    pretty_name = "Continue"
+
+    def detect(self) -> Path | None:
+        if _yaml_path().exists():
+            return _yaml_path()
+        if _json_path().exists():
+            # Continue is installed (legacy JSON); the configure() call will
+            # migrate it to YAML.
+            return _yaml_path()
+        return None
+
+    def configure(self, ctx: ConfigureContext) -> AgentResult:
+        _dir().mkdir(parents=True, exist_ok=True)
+        backups: list[Path] = []
+        notes: list[str] = []
+
+        # ── migration: only-JSON → write YAML and back up JSON ───────
+        if _json_path().exists() and not _yaml_path().exists():
+            migration_backups = _migrate_legacy_json(_json_path(), _yaml_path())
+            backups.extend(migration_backups)
+            notes.append(
+                "Migrated legacy ~/.continue/config.json to config.yaml "
+                f"(backup: {migration_backups[0].name})."
+            )
+
+        yaml_path = _yaml_path()
+        if yaml_path.exists():
+            backup = backup_once(yaml_path)
+            if backup is not None:
+                backups.append(backup)
+
+        payload = _load_yaml(yaml_path)
+        payload = _ensure_required_top_level(payload)
+
+        existing_models = payload.get("models") or []
+        merged = _merge_models(existing_models, ctx.catalog, ctx)
+        payload["models"] = merged
+
+        if not ctx.dry_run:
+            _dump_yaml(yaml_path, payload)
+
+        msg = f"{len(ctx.catalog)} models written, API base + key set in {yaml_path}."
+        if notes:
+            msg = "\n".join(notes) + "\n" + msg
+        return AgentResult(ResultStatus.SUCCESS, msg, tuple(backups))
+
+    def verify(self, ctx: ConfigureContext) -> AgentResult:
+        if not _yaml_path().exists():
+            return AgentResult(ResultStatus.ERROR, "Continue config.yaml not present")
+        payload = _load_yaml(_yaml_path())
+        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:
+        if not _yaml_path().exists():
+            return AgentResult(ResultStatus.SKIPPED, "Continue not installed")
+        backup = backup_once(_yaml_path())
+        payload = _load_yaml(_yaml_path())
+        payload["models"] = [
+            m for m in (payload.get("models") or []) if not is_substrate_managed(m)
+        ]
+        if not ctx.dry_run:
+            _dump_yaml(_yaml_path(), payload)
+        return AgentResult(
+            ResultStatus.SUCCESS,
+            "Removed substrate model entries from Continue",
+            (backup,) if backup else (),
+        )