xsync-cli 0.1.4__tar.gz → 0.2.1__tar.gz

{xsync_cli-0.1.4 → xsync_cli-0.2.1}/.gitignore

@@ -1,3 +1,6 @@
+# Superpowers working documents
+docs/superpowers/
+
 # Secrets
 .env
 .env.*

{xsync_cli-0.1.4 → xsync_cli-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: xsync-cli
-Version: 0.1.4
+Version: 0.2.1
 Summary: Sync the model list of an OpenAI-compatible endpoint into the Codex model catalog.
 License-Expression: MIT
 License-File: LICENSE
@@ -12,15 +12,29 @@ Description-Content-Type: text/markdown
 
 # xsync-cli
 
-Sync the model list of an OpenAI-compatible endpoint into the Codex model
-catalog.
+Point Codex and Claude Code at any OpenAI-compatible endpoint, with every
+model of that endpoint in the model picker.
 
-Codex reads its model list from a large JSON catalog file. A person must
-write that file by hand. The file becomes wrong when the endpoint adds a
-model or drops a model. `xsync` writes the file for you.
+```
+$ xsync claude
 
-    xsync codex
-    wrote 35 models to /Users/you/.codex/9router-models.json
+  claude · 9router
+    http://127.0.0.1:20128/v1
+    home: ~/.config/xsync/homes/9router/claude
+  ✓ 35 models ready. Your real claude is untouched.
+```
+
+A harness keeps its model list in a settings file. A person must write that
+file by hand, and the file becomes wrong when the endpoint adds a model or
+drops one. xSync writes the file for you.
+
+xSync opens the harness in a home of its own. The settings of the user stay
+as they are. Add `apply` when you do want to change them.
+
+| Harness | Needs |
+|---|---|
+| Codex | An endpoint that answers `GET /v1/models`. |
+| Claude Code | The same, and `POST /v1/messages` for the requests. |
 
 ## Install
 
@@ -50,19 +64,25 @@ The last question asks for the wire API:
 A wrong value breaks every request. Ask the operator of the endpoint when
 you do not know.
 
-### 2. Connect Codex to the endpoint
+### 2. Open a harness
 
-    xsync codex --init
+    xsync codex
+    xsync claude
 
-The command adds `[model_providers.<profile>]` to `~/.codex/config.toml` and
-points `model_catalog_json` at the catalog of the profile. Run this one time
-for each endpoint.
+The command builds a home for the profile, then starts the harness in that
+home. The real Codex and the real Claude Code of the user stay as they are.
 
-### 3. Sync
+Arguments after `--` go to the harness:
 
-    xsync codex
+    xsync claude -- --model cmc/deepseek/deepseek-v4-pro
+
+### 3. Or write the real harness
+
+    xsync codex apply
+    xsync claude apply
 
-Run this command again when the endpoint changes.
+The `apply` verb changes the real home of the user. Read **Safety** before
+you use it.
 
 ## Commands
 
@@ -72,18 +92,38 @@ Run this command again when the endpoint changes.
 | `xsync list` | Show the profiles. The active profile has a star. |
 | `xsync use <name>` | Set the active profile. |
 | `xsync remove <name>` | Delete a profile. |
-| `xsync codex` | Sync the active profile into the Codex catalog. |
-| `xsync codex --dry-run` | Show the difference. Write nothing. |
-| `xsync codex --profile <name>` | Use another profile for one run. |
-| `xsync codex --init` | Connect Codex to the endpoint of the profile. |
-| `xsync codex --reset` | Remove everything that xSync wrote. |
-| `xsync codex --reset --force` | Reset when no state file exists. It asks first. |
-| `xsync codex --reset --force --yes` | Reset with no question. Use this in a script. |
-| `xsync claude` | Sync the active profile into the Claude Code model picker. |
-| `xsync claude --init` | Point Claude Code at the endpoint of the profile. |
-| `xsync claude --dry-run` | Show the difference. Write nothing. |
-| `xsync claude --reset` | Remove everything that xSync wrote. |
 | `xsync help` | Show the help. `xsync help codex` explains one command. |
+| `xsync codex` | Open a Codex on the active profile, in its own home. |
+| `xsync claude` | Open a Claude Code the same way. |
+| `xsync codex -- <args>` | The arguments after `--` go to the harness. |
+| `xsync codex apply` | Write the real Codex of the user. |
+| `xsync claude apply` | Write the real Claude Code of the user. |
+| `xsync <harness> apply --dry-run` | Show the difference. Write nothing. |
+| `xsync <harness> apply --reset` | Remove everything that xSync wrote. |
+| `xsync <harness> apply --reset --force --yes` | Reset with no question. |
+| `xsync <harness> --profile <name>` | Use another profile for one run. |
+
+## The isolated home
+
+`xsync codex` and `xsync claude` do not change the settings of the user. Each
+one builds a home under `~/.config/xsync/homes/<profile>/`, and then starts
+the harness with `CODEX_HOME` or with `CLAUDE_CONFIG_DIR` set to that home.
+
+The home starts as a copy of the real settings file, so the hooks of the
+user and the trusted projects of the user stay. xSync then points the copy at
+the endpoint of the profile.
+
+The home shares the work of the user through a symbolic link:
+
+| Harness | Shared |
+|---|---|
+| Codex | `skills`, `plugins`, `marketplaces`, `memories`, `AGENTS.md` |
+| Claude Code | `agents`, `skills`, `plugins`, `hooks`, `commands`, `CLAUDE.md` |
+
+A session, a cache, and a log stay inside the isolated home. They never mix
+with the real home.
+
+Delete a home at any time. The next command builds it again.
 
 Exit codes: `0` for success, `1` for an error, `2` when the endpoint does not
 answer.
@@ -127,20 +167,22 @@ stops therefore leaves a working picker.
 
 ## Switch between endpoints
 
-Codex holds one model provider. Therefore one profile is active at a time.
+Each profile gets a home of its own. Therefore two endpoints never mix:
 
-    xsync codex --profile openrouter --init
+    xsync codex --profile openrouter
+    xsync codex --profile 9router
 
-This command points Codex at the other endpoint and fills the catalog in one
-step.
+A harness holds one model provider. Therefore `apply` writes one profile at
+a time:
 
-`xsync codex --profile X` without `--init` fills the catalog from X while
-Codex still routes somewhere else. Every model then fails at request time.
-xSync finds this mismatch before it writes, and it stops:
+    xsync codex apply --profile openrouter
 
-    catalog would come from "openrouter" (https://openrouter.ai/api/v1)
-    but Codex routes to "9router" (http://127.0.0.1:20128/v1)
-    run: xsync codex --profile openrouter --init
+`apply` always points the harness at the endpoint of the profile, so the
+model list and the endpoint always agree. A dry run does not point anything
+at anything, so it warns when the two disagree:
+
+    the rows would come from "openrouter" (https://openrouter.ai/api/v1)
+    but Claude Code talks to http://127.0.0.1:20128/v1
 
 ## The profile file
 
@@ -175,29 +217,35 @@ A glob pattern selects a model by name. The sign `*` means any characters.
 | `exclude = ["*-image-*", "*-tts-*"]` | Drop the image models and the speech models. |
 
 The `exclude` list always wins over the `include` list. Use the filters when
-an endpoint serves many models that you never choose in Codex.
+an endpoint serves many models that you never choose in a harness.
 
 The match ignores the letter case.
 
 ## Safety
 
+**The everyday commands write nothing outside `~/.config/xsync/`.** Only
+`apply` touches `~/.codex` or `~/.claude`.
+
 - The catalog write is atomic. xSync writes a temporary file, confirms the
   JSON, and then replaces the target. It keeps one backup with the suffix
   `.bak`.
-- The everyday `xsync codex` command never opens `config.toml` for writing.
-  Only `--init` and `--reset` do.
-- Codex writes `config.toml` while it runs. Therefore `--init` and `--reset`
-  hash the file before the edit and again before the replace. On a
-  difference they stop and write nothing.
-- `--reset` removes only what the state file `~/.codex/.xsync-state.json`
-  records. It never restores an old copy of `config.toml`, because Codex
-  adds project entries to that file over time.
-- `--reset` keeps the catalog backup `<name>.bak`. The backup is the only
-  way back after a reset.
-- With no state file, `--reset` prints the keys that it would remove and
-  then stops. Add `--force` to continue. The command then asks a question
-  before it removes anything. Add `--yes` to answer the question in a
-  script.
+- A harness writes its own settings file while it runs. Therefore `apply`
+  hashes the file before the edit and again before the replace. On a
+  difference it stops and writes nothing.
+- Claude Code rewrites `settings.json` from its own memory. An `apply` that
+  runs while Claude Code is open can therefore disappear. Close Claude Code
+  first, or use `xsync claude` and change nothing.
+- `apply --dry-run` writes nothing at all. It does not point the harness at
+  the endpoint either.
+- `apply --reset` removes only what the state file records. It never
+  restores an old copy of the settings, because a harness adds its own
+  entries to that file over time.
+- `apply --reset` keeps the backup `<name>.bak`. The backup is the only way
+  back after a reset.
+- With no state file, `apply --reset` prints the keys that it would remove
+  and then stops. Add `--force` to continue. The command then asks a
+  question before it removes anything. Add `--yes` to answer the question in
+  a script.
 - The setup hides the API key while you type it. It then shows the first
   five characters only, and it never shows the length of the key.
 - xSync never prints a whole API key.
@@ -214,9 +262,14 @@ keep the color in a pipe.
 |---|---|---|
 | `{base_url}/models` | yes | no |
 | `~/.config/xsync/profiles.toml` | yes | yes |
-| `~/.codex/<profile>-models.json` | yes | yes |
-| `~/.codex/config.toml` | yes | only with `--init` or `--reset` |
-| `~/.codex/.xsync-state.json` | yes | only with `--init` or `--reset` |
+| `~/.config/xsync/homes/...` | yes | yes |
+| `~/.codex/config.toml` | yes | only with `apply` |
+| `~/.codex/<profile>-models.json` | yes | only with `apply` |
+| `~/.claude/settings.json` | yes | only with `apply` |
+| `.xsync-state.json` in each home | yes | only with `apply` |
+
+xSync copies the real settings file when it builds an isolated home. It
+reads that file. It never writes it.
 
 ## The catalog fields
 

{xsync_cli-0.1.4 → xsync_cli-0.2.1}/README.md

@@ -1,14 +1,28 @@
 # xsync-cli
 
-Sync the model list of an OpenAI-compatible endpoint into the Codex model
-catalog.
+Point Codex and Claude Code at any OpenAI-compatible endpoint, with every
+model of that endpoint in the model picker.
 
-Codex reads its model list from a large JSON catalog file. A person must
-write that file by hand. The file becomes wrong when the endpoint adds a
-model or drops a model. `xsync` writes the file for you.
+```
+$ xsync claude
 
-    xsync codex
-    wrote 35 models to /Users/you/.codex/9router-models.json
+  claude · 9router
+    http://127.0.0.1:20128/v1
+    home: ~/.config/xsync/homes/9router/claude
+  ✓ 35 models ready. Your real claude is untouched.
+```
+
+A harness keeps its model list in a settings file. A person must write that
+file by hand, and the file becomes wrong when the endpoint adds a model or
+drops one. xSync writes the file for you.
+
+xSync opens the harness in a home of its own. The settings of the user stay
+as they are. Add `apply` when you do want to change them.
+
+| Harness | Needs |
+|---|---|
+| Codex | An endpoint that answers `GET /v1/models`. |
+| Claude Code | The same, and `POST /v1/messages` for the requests. |
 
 ## Install
 
@@ -38,19 +52,25 @@ The last question asks for the wire API:
 A wrong value breaks every request. Ask the operator of the endpoint when
 you do not know.
 
-### 2. Connect Codex to the endpoint
+### 2. Open a harness
 
-    xsync codex --init
+    xsync codex
+    xsync claude
 
-The command adds `[model_providers.<profile>]` to `~/.codex/config.toml` and
-points `model_catalog_json` at the catalog of the profile. Run this one time
-for each endpoint.
+The command builds a home for the profile, then starts the harness in that
+home. The real Codex and the real Claude Code of the user stay as they are.
 
-### 3. Sync
+Arguments after `--` go to the harness:
 
-    xsync codex
+    xsync claude -- --model cmc/deepseek/deepseek-v4-pro
+
+### 3. Or write the real harness
+
+    xsync codex apply
+    xsync claude apply
 
-Run this command again when the endpoint changes.
+The `apply` verb changes the real home of the user. Read **Safety** before
+you use it.
 
 ## Commands
 
@@ -60,18 +80,38 @@ Run this command again when the endpoint changes.
 | `xsync list` | Show the profiles. The active profile has a star. |
 | `xsync use <name>` | Set the active profile. |
 | `xsync remove <name>` | Delete a profile. |
-| `xsync codex` | Sync the active profile into the Codex catalog. |
-| `xsync codex --dry-run` | Show the difference. Write nothing. |
-| `xsync codex --profile <name>` | Use another profile for one run. |
-| `xsync codex --init` | Connect Codex to the endpoint of the profile. |
-| `xsync codex --reset` | Remove everything that xSync wrote. |
-| `xsync codex --reset --force` | Reset when no state file exists. It asks first. |
-| `xsync codex --reset --force --yes` | Reset with no question. Use this in a script. |
-| `xsync claude` | Sync the active profile into the Claude Code model picker. |
-| `xsync claude --init` | Point Claude Code at the endpoint of the profile. |
-| `xsync claude --dry-run` | Show the difference. Write nothing. |
-| `xsync claude --reset` | Remove everything that xSync wrote. |
 | `xsync help` | Show the help. `xsync help codex` explains one command. |
+| `xsync codex` | Open a Codex on the active profile, in its own home. |
+| `xsync claude` | Open a Claude Code the same way. |
+| `xsync codex -- <args>` | The arguments after `--` go to the harness. |
+| `xsync codex apply` | Write the real Codex of the user. |
+| `xsync claude apply` | Write the real Claude Code of the user. |
+| `xsync <harness> apply --dry-run` | Show the difference. Write nothing. |
+| `xsync <harness> apply --reset` | Remove everything that xSync wrote. |
+| `xsync <harness> apply --reset --force --yes` | Reset with no question. |
+| `xsync <harness> --profile <name>` | Use another profile for one run. |
+
+## The isolated home
+
+`xsync codex` and `xsync claude` do not change the settings of the user. Each
+one builds a home under `~/.config/xsync/homes/<profile>/`, and then starts
+the harness with `CODEX_HOME` or with `CLAUDE_CONFIG_DIR` set to that home.
+
+The home starts as a copy of the real settings file, so the hooks of the
+user and the trusted projects of the user stay. xSync then points the copy at
+the endpoint of the profile.
+
+The home shares the work of the user through a symbolic link:
+
+| Harness | Shared |
+|---|---|
+| Codex | `skills`, `plugins`, `marketplaces`, `memories`, `AGENTS.md` |
+| Claude Code | `agents`, `skills`, `plugins`, `hooks`, `commands`, `CLAUDE.md` |
+
+A session, a cache, and a log stay inside the isolated home. They never mix
+with the real home.
+
+Delete a home at any time. The next command builds it again.
 
 Exit codes: `0` for success, `1` for an error, `2` when the endpoint does not
 answer.
@@ -115,20 +155,22 @@ stops therefore leaves a working picker.
 
 ## Switch between endpoints
 
-Codex holds one model provider. Therefore one profile is active at a time.
+Each profile gets a home of its own. Therefore two endpoints never mix:
 
-    xsync codex --profile openrouter --init
+    xsync codex --profile openrouter
+    xsync codex --profile 9router
 
-This command points Codex at the other endpoint and fills the catalog in one
-step.
+A harness holds one model provider. Therefore `apply` writes one profile at
+a time:
 
-`xsync codex --profile X` without `--init` fills the catalog from X while
-Codex still routes somewhere else. Every model then fails at request time.
-xSync finds this mismatch before it writes, and it stops:
+    xsync codex apply --profile openrouter
 
-    catalog would come from "openrouter" (https://openrouter.ai/api/v1)
-    but Codex routes to "9router" (http://127.0.0.1:20128/v1)
-    run: xsync codex --profile openrouter --init
+`apply` always points the harness at the endpoint of the profile, so the
+model list and the endpoint always agree. A dry run does not point anything
+at anything, so it warns when the two disagree:
+
+    the rows would come from "openrouter" (https://openrouter.ai/api/v1)
+    but Claude Code talks to http://127.0.0.1:20128/v1
 
 ## The profile file
 
@@ -163,29 +205,35 @@ A glob pattern selects a model by name. The sign `*` means any characters.
 | `exclude = ["*-image-*", "*-tts-*"]` | Drop the image models and the speech models. |
 
 The `exclude` list always wins over the `include` list. Use the filters when
-an endpoint serves many models that you never choose in Codex.
+an endpoint serves many models that you never choose in a harness.
 
 The match ignores the letter case.
 
 ## Safety
 
+**The everyday commands write nothing outside `~/.config/xsync/`.** Only
+`apply` touches `~/.codex` or `~/.claude`.
+
 - The catalog write is atomic. xSync writes a temporary file, confirms the
   JSON, and then replaces the target. It keeps one backup with the suffix
   `.bak`.
-- The everyday `xsync codex` command never opens `config.toml` for writing.
-  Only `--init` and `--reset` do.
-- Codex writes `config.toml` while it runs. Therefore `--init` and `--reset`
-  hash the file before the edit and again before the replace. On a
-  difference they stop and write nothing.
-- `--reset` removes only what the state file `~/.codex/.xsync-state.json`
-  records. It never restores an old copy of `config.toml`, because Codex
-  adds project entries to that file over time.
-- `--reset` keeps the catalog backup `<name>.bak`. The backup is the only
-  way back after a reset.
-- With no state file, `--reset` prints the keys that it would remove and
-  then stops. Add `--force` to continue. The command then asks a question
-  before it removes anything. Add `--yes` to answer the question in a
-  script.
+- A harness writes its own settings file while it runs. Therefore `apply`
+  hashes the file before the edit and again before the replace. On a
+  difference it stops and writes nothing.
+- Claude Code rewrites `settings.json` from its own memory. An `apply` that
+  runs while Claude Code is open can therefore disappear. Close Claude Code
+  first, or use `xsync claude` and change nothing.
+- `apply --dry-run` writes nothing at all. It does not point the harness at
+  the endpoint either.
+- `apply --reset` removes only what the state file records. It never
+  restores an old copy of the settings, because a harness adds its own
+  entries to that file over time.
+- `apply --reset` keeps the backup `<name>.bak`. The backup is the only way
+  back after a reset.
+- With no state file, `apply --reset` prints the keys that it would remove
+  and then stops. Add `--force` to continue. The command then asks a
+  question before it removes anything. Add `--yes` to answer the question in
+  a script.
 - The setup hides the API key while you type it. It then shows the first
   five characters only, and it never shows the length of the key.
 - xSync never prints a whole API key.
@@ -202,9 +250,14 @@ keep the color in a pipe.
 |---|---|---|
 | `{base_url}/models` | yes | no |
 | `~/.config/xsync/profiles.toml` | yes | yes |
-| `~/.codex/<profile>-models.json` | yes | yes |
-| `~/.codex/config.toml` | yes | only with `--init` or `--reset` |
-| `~/.codex/.xsync-state.json` | yes | only with `--init` or `--reset` |
+| `~/.config/xsync/homes/...` | yes | yes |
+| `~/.codex/config.toml` | yes | only with `apply` |
+| `~/.codex/<profile>-models.json` | yes | only with `apply` |
+| `~/.claude/settings.json` | yes | only with `apply` |
+| `.xsync-state.json` in each home | yes | only with `apply` |
+
+xSync copies the real settings file when it builds an isolated home. It
+reads that file. It never writes it.
 
 ## The catalog fields
 

{xsync_cli-0.1.4 → xsync_cli-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "xsync-cli"
-version = "0.1.4"
+version = "0.2.1"
 description = "Sync the model list of an OpenAI-compatible endpoint into the Codex model catalog."
 readme = "README.md"
 requires-python = ">=3.11"

xsync_cli-0.2.1/src/xsync_cli/adapters/isolated.py

@@ -0,0 +1,118 @@
+"""The builder of an isolated harness home.
+
+The functions here write into a home that xSync owns. They read the
+real home of the user, but they never write into it.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Sequence
+from pathlib import Path
+
+import tomlkit
+
+from xsync_cli.adapters.claude import load_rules as load_claude_rules
+from xsync_cli.adapters.claude import render_rows
+from xsync_cli.adapters.codex import load_rules as load_codex_rules
+from xsync_cli.adapters.codex import render_catalog
+from xsync_cli.core.atomic import write_json_atomic
+from xsync_cli.core.homes import SHARED_CLAUDE, SHARED_CODEX, link_shared
+from xsync_cli.core.model import Model
+from xsync_cli.core.profiles import Profile
+
+
+def prepare_codex_home(
+    home: Path,
+    real_home: Path,
+    profile: Profile,
+    api_key: str | None,
+    models: Sequence[Model],
+) -> Path:
+    """Build a Codex home that talks to the endpoint of the profile.
+
+    The function copies the real `config.toml` as a base, so the trusted
+    projects of the user stay. It then points the copy at the endpoint.
+    """
+    home.mkdir(parents=True, exist_ok=True)
+
+    catalog_path = home / f"{profile.name}-models.json"
+    write_json_atomic(
+        catalog_path, render_catalog(models, load_codex_rules()), keep_backup=False
+    )
+
+    real_config = real_home / "config.toml"
+    document = (
+        tomlkit.parse(real_config.read_text(encoding="utf-8"))
+        if real_config.exists()
+        else tomlkit.document()
+    )
+
+    document["model_catalog_json"] = str(catalog_path)
+    document["model_provider"] = profile.name
+
+    providers = document.get("model_providers")
+    if providers is None:
+        providers = tomlkit.table(is_super_table=True)
+        document["model_providers"] = providers
+
+    entry = tomlkit.table()
+    entry["name"] = profile.name
+    entry["base_url"] = profile.base_url
+    entry["wire_api"] = profile.wire_api
+    if api_key:
+        headers = tomlkit.table()
+        headers["Authorization"] = f"Bearer {api_key}"
+        entry["http_headers"] = headers
+    providers[profile.name] = entry
+
+    temporary = home / "config.toml.tmp"
+    temporary.write_text(tomlkit.dumps(document), encoding="utf-8")
+    os.replace(temporary, home / "config.toml")
+
+    link_shared(real_home, home, SHARED_CODEX)
+    return home
+
+
+def prepare_claude_home(
+    home: Path,
+    real_home: Path,
+    profile: Profile,
+    api_key: str | None,
+    models: Sequence[Model],
+) -> Path:
+    """Build a Claude Code home that talks to the endpoint.
+
+    The function copies the real `settings.json` as a base, so the hooks
+    of the user stay. It then adds the endpoint and the picker rows.
+    """
+    home.mkdir(parents=True, exist_ok=True)
+
+    real_settings = real_home / "settings.json"
+    settings: dict = {}
+    if real_settings.exists():
+        try:
+            loaded = json.loads(real_settings.read_text(encoding="utf-8"))
+            if isinstance(loaded, dict):
+                settings = loaded
+        except json.JSONDecodeError:
+            settings = {}
+
+    environment = dict(settings.get("env") or {})
+    environment["ANTHROPIC_BASE_URL"] = profile.base_url
+    if api_key:
+        environment["ANTHROPIC_AUTH_TOKEN"] = api_key
+    settings["env"] = environment
+
+    rows = render_rows(models, load_claude_rules())
+    settings["modelPicker"] = {"options": rows, "replaceBuiltInOptions": False}
+
+    temporary = home / "settings.json.tmp"
+    temporary.write_text(
+        json.dumps(settings, indent=2, ensure_ascii=False) + "\n", encoding="utf-8"
+    )
+    os.replace(temporary, home / "settings.json")
+
+    link_shared(real_home, home, SHARED_CLAUDE)
+    return home