xsync-cli 0.1.0__py3-none-any.whl

xsync_cli/cli.py

@@ -0,0 +1,321 @@
+"""The xsync command line."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+from xsync_cli.adapters.codex import load_rules, render_catalog
+from xsync_cli.adapters.codex_config import (
+    STATE_FILENAME,
+    ConfigError,
+    State,
+    catalog_path_for,
+    check_provider_match,
+    clear_state,
+    default_codex_home,
+    read_config,
+    read_state,
+    write_state,
+)
+from xsync_cli.adapters.codex_wiring import init_config, known_removals, reset_config
+from xsync_cli.core.atomic import write_json_atomic
+from xsync_cli.core.diff import diff_catalogs
+from xsync_cli.core.filters import apply_filters
+from xsync_cli.core.profiles import (
+    WIRE_APIS,
+    Profile,
+    ProfileError,
+    ProfileStore,
+    default_store_path,
+)
+from xsync_cli.sources.openai_compat import (
+    EndpointUnreachable,
+    SourceError,
+    fetch_models,
+)
+
+EXIT_OK = 0
+EXIT_ERROR = 1
+EXIT_UNREACHABLE = 2
+
+
+def store_path() -> Path:
+    """The profile file. The variable XSYNC_PROFILES wins."""
+    override = os.environ.get("XSYNC_PROFILES")
+    return Path(override) if override else default_store_path()
+
+
+def open_store() -> ProfileStore:
+    store = ProfileStore(store_path())
+    store.load()
+    return store
+
+
+def _ask(prompt: str, default: str = "") -> str:
+    suffix = f" [{default}]" if default else ""
+    answer = input(f"{prompt}{suffix}: ").strip()
+    return answer or default
+
+
+def _ask_list(prompt: str) -> list[str]:
+    answer = _ask(prompt)
+    return [part.strip() for part in answer.split(",") if part.strip()]
+
+
+def cmd_setup(args: argparse.Namespace) -> int:
+    """Make a profile."""
+    store = open_store()
+
+    name = _ask("profile name")
+    if not name:
+        print("the profile name cannot be empty.", file=sys.stderr)
+        return EXIT_ERROR
+
+    base_url = _ask("base URL (for example http://127.0.0.1:20128/v1)")
+    if not base_url:
+        print("the base URL cannot be empty.", file=sys.stderr)
+        return EXIT_ERROR
+
+    api_key = _ask("API key (leave empty when the endpoint needs none)")
+    include = _ask_list("include globs, separated by a comma (optional)")
+    exclude = _ask_list("exclude globs, separated by a comma (optional)")
+
+    print(f"testing {base_url}/models …")
+    try:
+        models = fetch_models(base_url, api_key or None)
+    except EndpointUnreachable as error:
+        print(f"error: {error}", file=sys.stderr)
+        return EXIT_UNREACHABLE
+    except SourceError as error:
+        print(f"error: {error}", file=sys.stderr)
+        return EXIT_ERROR
+
+    print(f"\n{len(models)} models:")
+    for model in models:
+        window = f"{model.context_window:,}" if model.context_window else "unknown"
+        flags = ",".join(
+            flag
+            for flag, on in (
+                ("tools", model.tools),
+                ("reasoning", model.reasoning),
+                ("vision", model.vision),
+                ("search", model.search),
+            )
+            if on
+        )
+        print(f"  {model.slug:<48} {window:>12}  {flags}")
+
+    print()
+    wire_api = _ask(f"wire API ({' or '.join(WIRE_APIS)})", "chat")
+
+    try:
+        profile = Profile(
+            name=name,
+            base_url=base_url,
+            api_key=api_key or None,
+            api_key_env=None,
+            wire_api=wire_api,
+            include=include,
+            exclude=exclude,
+        )
+    except ProfileError as error:
+        print(f"error: {error}", file=sys.stderr)
+        return EXIT_ERROR
+
+    store.add(profile)
+    store.save()
+    print(f"\nsaved profile {name!r} to {store.path}")
+    if store.active == name:
+        print(f"profile {name!r} is now active")
+    return EXIT_OK
+
+
+def cmd_list(args: argparse.Namespace) -> int:
+    """Show the profiles."""
+    store = open_store()
+    if not store.names():
+        print("no profile exists. Run `xsync setup` first.")
+        return EXIT_OK
+    for name in store.names():
+        mark = "*" if name == store.active else " "
+        profile = store.get(name)
+        print(f"{mark} {name:<20} {profile.base_url:<40} {profile.wire_api}")
+    return EXIT_OK
+
+
+def cmd_use(args: argparse.Namespace) -> int:
+    """Set the active profile."""
+    store = open_store()
+    try:
+        store.set_active(args.name)
+    except ProfileError as error:
+        print(f"error: {error}", file=sys.stderr)
+        return EXIT_ERROR
+    store.save()
+    print(f"active profile: {args.name}")
+    return EXIT_OK
+
+
+def cmd_remove(args: argparse.Namespace) -> int:
+    """Delete a profile."""
+    store = open_store()
+    try:
+        store.remove(args.name)
+    except ProfileError as error:
+        print(f"error: {error}", file=sys.stderr)
+        return EXIT_ERROR
+    store.save()
+    print(f"removed profile {args.name!r}")
+    return EXIT_OK
+
+
+def _load_catalog(path: Path) -> dict | None:
+    """The current catalog, or None when it is absent or damaged."""
+    if not path.exists():
+        return None
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return None
+
+
+def _do_reset(codex_home: Path, profile_name: str, force: bool) -> int:
+    """Remove everything that xSync wrote."""
+    state_path = codex_home / STATE_FILENAME
+    state = read_state(state_path)
+
+    if state is None:
+        planned = known_removals(profile_name)
+        if not force:
+            print("no state file exists. xSync would remove:")
+            for key in planned.keys_written:
+                print(f"  key    {key}")
+            for block in planned.blocks_written:
+                print(f"  block  [{block}]")
+            print("\nadd --force to continue.", file=sys.stderr)
+            return EXIT_ERROR
+        state = State(
+            profile=profile_name,
+            keys_written=planned.keys_written,
+            blocks_written=planned.blocks_written,
+            files_written=[str(codex_home / f"{profile_name}-models.json")],
+            config_sha256="",
+            written_at="",
+        )
+
+    removed = reset_config(codex_home / "config.toml", state)
+    clear_state(state_path)
+    for name in removed:
+        print(f"removed {name}")
+    print("Codex is back at its own defaults.")
+    return EXIT_OK
+
+
+def cmd_codex(args: argparse.Namespace) -> int:
+    """Sync a profile into the Codex catalog."""
+    store = open_store()
+    codex_home = default_codex_home()
+    config_path = codex_home / "config.toml"
+
+    try:
+        profile = store.get(args.profile) if args.profile else store.active_profile()
+    except ProfileError as error:
+        print(f"error: {error}", file=sys.stderr)
+        return EXIT_ERROR
+
+    if args.reset:
+        try:
+            return _do_reset(codex_home, profile.name, args.force)
+        except ConfigError as error:
+            print(f"error: {error}", file=sys.stderr)
+            return EXIT_ERROR
+
+    catalog_path = catalog_path_for(profile, codex_home)
+
+    if args.init:
+        try:
+            api_key = profile.resolve_key(os.environ)
+            state = init_config(config_path, profile, catalog_path, api_key)
+        except (ConfigError, ProfileError) as error:
+            print(f"error: {error}", file=sys.stderr)
+            return EXIT_ERROR
+        write_state(codex_home / STATE_FILENAME, state)
+        print(f"Codex now routes to {profile.name!r} ({profile.base_url})")
+
+    try:
+        api_key = profile.resolve_key(os.environ)
+        models = fetch_models(profile.base_url, api_key)
+    except EndpointUnreachable as error:
+        print(f"error: {error}", file=sys.stderr)
+        return EXIT_UNREACHABLE
+    except (SourceError, ProfileError) as error:
+        print(f"error: {error}", file=sys.stderr)
+        return EXIT_ERROR
+
+    models = apply_filters(models, profile.include, profile.exclude)
+
+    config = read_config(config_path)
+    message = check_provider_match(config, profile)
+    if message:
+        if args.dry_run:
+            print(f"warning:\n{message}\n")
+        else:
+            print(f"error:\n{message}", file=sys.stderr)
+            return EXIT_ERROR
+
+    catalog = render_catalog(models, load_rules())
+    report = diff_catalogs(_load_catalog(catalog_path), catalog)
+    print(report.render())
+
+    if args.dry_run:
+        print("no files written (--dry-run)")
+        return EXIT_OK
+
+    write_json_atomic(catalog_path, catalog)
+    print(f"wrote {len(catalog['models'])} models to {catalog_path}")
+    return EXIT_OK
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="xsync",
+        description="Sync the model list of an OpenAI-compatible endpoint into a harness.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("setup", help="make a profile").set_defaults(func=cmd_setup)
+    sub.add_parser("list", help="show the profiles").set_defaults(func=cmd_list)
+
+    use = sub.add_parser("use", help="set the active profile")
+    use.add_argument("name")
+    use.set_defaults(func=cmd_use)
+
+    remove = sub.add_parser("remove", help="delete a profile")
+    remove.add_argument("name")
+    remove.set_defaults(func=cmd_remove)
+
+    codex = sub.add_parser("codex", help="sync a profile into the Codex catalog")
+    codex.add_argument("--profile", help="use this profile for one run")
+    codex.add_argument("--dry-run", action="store_true", help="show the difference only")
+    codex.add_argument("--init", action="store_true", help="wire Codex to the endpoint")
+    codex.add_argument(
+        "--reset", action="store_true", help="remove everything xSync wrote"
+    )
+    codex.add_argument("--force", action="store_true", help="reset without a state file")
+    codex.set_defaults(func=cmd_codex)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return args.func(args)
+    except (ProfileError, ConfigError) as error:
+        print(f"error: {error}", file=sys.stderr)
+        return EXIT_ERROR

xsync_cli/core/atomic.py

@@ -0,0 +1,28 @@
+"""The safe file write."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+
+def write_json_atomic(path: Path, payload: dict[str, Any], keep_backup: bool = True) -> None:
+    """Write JSON without a partial file.
+
+    The function writes a temporary file in the same directory, confirms
+    that the file holds valid JSON, and then replaces the target. It
+    keeps one backup with the suffix `.bak`.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_name(path.name + ".tmp")
+
+    text = json.dumps(payload, indent=2, ensure_ascii=False)
+    json.loads(text)
+
+    temporary.write_text(text, encoding="utf-8")
+    if keep_backup and path.exists():
+        backup = path.with_name(path.name + ".bak")
+        backup.write_bytes(path.read_bytes())
+    os.replace(temporary, path)

xsync_cli/core/diff.py

@@ -0,0 +1,81 @@
+"""The difference between two catalogs."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class CatalogDiff:
+    """The report of one sync."""
+
+    added: list[str]
+    removed: list[str]
+    changed: list[tuple[str, list[str]]]
+    unchanged: list[str]
+
+    @property
+    def is_empty(self) -> bool:
+        """True when the catalog does not change."""
+        return not (self.added or self.removed or self.changed)
+
+    def render(self, limit: int = 8) -> str:
+        """The report as text."""
+        lines: list[str] = []
+        if self.added:
+            lines.append(f"+ {len(self.added)} added      {self._sample(self.added, limit)}")
+        if self.removed:
+            lines.append(
+                f"- {len(self.removed)} removed    {self._sample(self.removed, limit)}"
+            )
+        if self.changed:
+            names = [
+                f"{slug} ({self._fields(fields)})" for slug, fields in self.changed
+            ]
+            lines.append(f"~ {len(self.changed)} changed    {self._sample(names, limit)}")
+        lines.append(f"  {len(self.unchanged)} unchanged")
+        return "\n".join(lines)
+
+    @staticmethod
+    def _fields(fields: list[str], limit: int = 3) -> str:
+        """The field names of one changed model, cut short."""
+        head = ", ".join(fields[:limit])
+        return head if len(fields) <= limit else f"{head}, +{len(fields) - limit} more"
+
+    @staticmethod
+    def _sample(items: list[str], limit: int) -> str:
+        head = ", ".join(items[:limit])
+        return head if len(items) <= limit else f"{head}, … (+{len(items) - limit})"
+
+
+def _by_slug(catalog: dict[str, Any] | None) -> dict[str, dict[str, Any]]:
+    if not catalog:
+        return {}
+    return {entry["slug"]: entry for entry in catalog.get("models", []) if "slug" in entry}
+
+
+def diff_catalogs(old: dict[str, Any] | None, new: dict[str, Any]) -> CatalogDiff:
+    """Compare two catalogs by slug."""
+    old_map = _by_slug(old)
+    new_map = _by_slug(new)
+
+    added = [slug for slug in new_map if slug not in old_map]
+    removed = [slug for slug in old_map if slug not in new_map]
+    changed: list[tuple[str, list[str]]] = []
+    unchanged: list[str] = []
+
+    for slug, entry in new_map.items():
+        if slug not in old_map:
+            continue
+        fields = sorted(
+            key
+            for key in set(entry) | set(old_map[slug])
+            if entry.get(key) != old_map[slug].get(key)
+        )
+        if fields:
+            changed.append((slug, fields))
+        else:
+            unchanged.append(slug)
+
+    return CatalogDiff(added=added, removed=removed, changed=changed, unchanged=unchanged)

xsync_cli/core/filters.py

@@ -0,0 +1,33 @@
+"""The include and exclude glob rules."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from fnmatch import fnmatch
+
+from xsync_cli.core.model import Model
+
+
+def _matches_any(slug: str, patterns: Sequence[str]) -> bool:
+    lowered = slug.lower()
+    return any(fnmatch(lowered, pattern.lower()) for pattern in patterns)
+
+
+def apply_filters(
+    models: Sequence[Model],
+    include: Sequence[str],
+    exclude: Sequence[str],
+) -> list[Model]:
+    """Keep the models that the rules allow.
+
+    An empty include list keeps every model. The exclude list always
+    wins over the include list. The match ignores the letter case.
+    """
+    kept: list[Model] = []
+    for candidate in models:
+        if include and not _matches_any(candidate.slug, include):
+            continue
+        if exclude and _matches_any(candidate.slug, exclude):
+            continue
+        kept.append(candidate)
+    return kept

xsync_cli/core/model.py

@@ -0,0 +1,35 @@
+"""The provider-neutral model record."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class Model:
+    """One model, as an endpoint reports it.
+
+    The fields hold facts about the model. They do not hold harness
+    settings. An endpoint that reports no capabilities gives None or
+    False. The adapter rules then supply a value.
+    """
+
+    slug: str
+    context_window: int | None
+    max_output: int | None
+    vision: bool
+    reasoning: bool
+    tools: bool
+    search: bool
+    owned_by: str | None
+
+    @property
+    def prefix(self) -> str:
+        """The first slug segment, or an empty string for a flat slug."""
+        head, sep, _ = self.slug.partition("/")
+        return head if sep else ""
+
+    @property
+    def leaf_name(self) -> str:
+        """The last slug segment."""
+        return self.slug.rsplit("/", 1)[-1]

xsync_cli/core/profiles.py

@@ -0,0 +1,166 @@
+"""The profile store.
+
+A profile holds the connection data for one OpenAI-compatible endpoint.
+The store keeps the profiles in a TOML file with mode 0600.
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import tomlkit
+
+WIRE_APIS = ("chat", "responses")
+
+
+class ProfileError(Exception):
+    """The profile data is wrong, or the profile does not exist."""
+
+
+def default_store_path() -> Path:
+    """The default path of the profile file."""
+    return Path.home() / ".config" / "xsync" / "profiles.toml"
+
+
+@dataclass(frozen=True, slots=True)
+class Profile:
+    """One endpoint, with its filters."""
+
+    name: str
+    base_url: str
+    api_key: str | None
+    api_key_env: str | None
+    wire_api: str
+    include: list[str] = field(default_factory=list)
+    exclude: list[str] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        if self.api_key and self.api_key_env:
+            raise ProfileError(
+                f"profile {self.name!r} sets api_key and api_key_env. "
+                "Set one, not both."
+            )
+        if self.wire_api not in WIRE_APIS:
+            raise ProfileError(
+                f"profile {self.name!r} has wire_api {self.wire_api!r}. "
+                f"Use one of {', '.join(WIRE_APIS)}."
+            )
+        object.__setattr__(self, "base_url", self.base_url.rstrip("/"))
+
+    def resolve_key(self, env: Mapping[str, str]) -> str | None:
+        """The API key, or None when the profile has no key."""
+        if self.api_key:
+            return self.api_key
+        if self.api_key_env:
+            value = env.get(self.api_key_env)
+            if not value:
+                raise ProfileError(
+                    f"profile {self.name!r} needs the variable "
+                    f"{self.api_key_env}. The variable is empty or absent."
+                )
+            return value
+        return None
+
+    def to_table(self) -> dict[str, object]:
+        """The profile as plain data, without the name."""
+        table: dict[str, object] = {"base_url": self.base_url, "wire_api": self.wire_api}
+        if self.api_key:
+            table["api_key"] = self.api_key
+        if self.api_key_env:
+            table["api_key_env"] = self.api_key_env
+        if self.include:
+            table["include"] = list(self.include)
+        if self.exclude:
+            table["exclude"] = list(self.exclude)
+        return table
+
+
+class ProfileStore:
+    """The reader and the writer of the profile file."""
+
+    def __init__(self, path: Path) -> None:
+        self.path = path
+        self.active: str | None = None
+        self._profiles: dict[str, Profile] = {}
+
+    def load(self) -> None:
+        """Read the file. An absent file gives an empty store."""
+        if not self.path.exists():
+            self.active = None
+            self._profiles = {}
+            return
+        data = tomllib.loads(self.path.read_text(encoding="utf-8"))
+        self.active = data.get("active")
+        self._profiles = {}
+        for name, table in (data.get("profiles") or {}).items():
+            self._profiles[name] = Profile(
+                name=name,
+                base_url=str(table.get("base_url", "")),
+                api_key=table.get("api_key"),
+                api_key_env=table.get("api_key_env"),
+                wire_api=str(table.get("wire_api", "chat")),
+                include=list(table.get("include", [])),
+                exclude=list(table.get("exclude", [])),
+            )
+        if self.active not in self._profiles:
+            self.active = next(iter(self._profiles), None)
+
+    def save(self) -> None:
+        """Write the file with mode 0600."""
+        document = tomlkit.document()
+        if self.active:
+            document["active"] = self.active
+        profiles = tomlkit.table(is_super_table=True)
+        for name, profile in self._profiles.items():
+            entry = tomlkit.table()
+            for key, value in profile.to_table().items():
+                entry[key] = value
+            profiles[name] = entry
+        document["profiles"] = profiles
+
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        temporary = self.path.with_suffix(".tmp")
+        temporary.write_text(tomlkit.dumps(document), encoding="utf-8")
+        os.chmod(temporary, 0o600)
+        os.replace(temporary, self.path)
+
+    def add(self, profile: Profile) -> None:
+        """Add a profile. The first profile becomes the active profile."""
+        self._profiles[profile.name] = profile
+        if self.active is None:
+            self.active = profile.name
+
+    def get(self, name: str) -> Profile:
+        """One profile by name."""
+        try:
+            return self._profiles[name]
+        except KeyError:
+            raise ProfileError(f"unknown profile {name!r}") from None
+
+    def remove(self, name: str) -> None:
+        """Delete a profile. Move the active name when necessary."""
+        if name not in self._profiles:
+            raise ProfileError(f"unknown profile {name!r}")
+        del self._profiles[name]
+        if self.active == name:
+            self.active = next(iter(self._profiles), None)
+
+    def names(self) -> list[str]:
+        """The profile names, in insertion order."""
+        return list(self._profiles)
+
+    def set_active(self, name: str) -> None:
+        """Make one profile the active profile."""
+        if name not in self._profiles:
+            raise ProfileError(f"unknown profile {name!r}")
+        self.active = name
+
+    def active_profile(self) -> Profile:
+        """The active profile."""
+        if not self.active:
+            raise ProfileError("no profile exists. Run `xsync setup` first.")
+        return self.get(self.active)