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

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: xsync-cli
-Version: 0.2.0
+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
 
@@ -153,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
+    xsync codex --profile 9router
 
-    xsync codex --profile openrouter --init
+A harness holds one model provider. Therefore `apply` writes one profile at
+a time:
 
-This command points Codex at the other endpoint and fills the catalog in one
-step.
+    xsync codex apply --profile openrouter
 
-`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:
+`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:
 
-    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
+    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
 
@@ -201,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.
@@ -240,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.2.0 → 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
 
@@ -141,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
+    xsync codex --profile 9router
 
-    xsync codex --profile openrouter --init
+A harness holds one model provider. Therefore `apply` writes one profile at
+a time:
 
-This command points Codex at the other endpoint and fills the catalog in one
-step.
+    xsync codex apply --profile openrouter
 
-`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:
+`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:
 
-    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
+    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
 
@@ -189,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.
@@ -228,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.2.0 → xsync_cli-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "xsync-cli"
-version = "0.2.0"
+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.0 → xsync_cli-0.2.1}/src/xsync_cli/cli.py

@@ -488,36 +488,111 @@ def _print_report(report, profile: Profile, total: int) -> None:
     print("   " + "   ".join(parts))
 
 
-EPILOG = """\
-examples:
-  xsync setup                      make a profile, and read the model list
-  xsync list                       show the profiles. The active one has a star
-  xsync use openrouter             set the active profile
+HELP_GROUPS = (
+    (
+        "PROFILES",
+        (
+            ("setup", "make a profile, and read the model list"),
+            ("list", "show the profiles. The active one has a dot"),
+            ("use <name>", "set the active profile"),
+            ("remove <name>", "delete a profile"),
+        ),
+    ),
+    (
+        "HARNESSES",
+        (
+            ("codex", "open a Codex on the profile, in its own home"),
+            ("claude", "open a Claude Code the same way"),
+            ("<harness> apply", "write the real harness of the user"),
+        ),
+    ),
+    (
+        "HELP",
+        (
+            ("help", "show this page"),
+            ("help <command>", "show the options of one command"),
+        ),
+    ),
+)
+
+HELP_OPTIONS = (
+    ("--profile <name>", "use another profile for one run"),
+    ("-- <args>", "send the arguments after -- to the harness"),
+    ("apply --dry-run", "show the difference. Write nothing"),
+    ("apply --reset", "remove everything that xsync wrote"),
+)
+
+HELP_FILES = (
+    ("~/.config/xsync/profiles.toml", "the profiles"),
+    ("~/.config/xsync/homes/", "one home for each profile and harness"),
+    ("~/.codex, ~/.claude", "only `apply` writes these"),
+)
+
+HELP_EXIT = (
+    ("0", "success"),
+    ("1", "an error"),
+    ("2", "the endpoint does not answer"),
+)
 
-  xsync codex                      open a Codex on the profile, in its own home
-  xsync claude                     open a Claude Code the same way
-  xsync claude -- --model a/b      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 codex apply --dry-run      show the difference. Write nothing
-  xsync codex apply --reset        remove everything that xsync wrote
+def _version() -> str:
+    """The installed version of the tool."""
+    try:
+        from importlib.metadata import version
+
+        return version("xsync-cli")
+    except Exception:  # noqa: BLE001
+        return "unknown"
+
+
+def render_help() -> str:
+    """The help page of the tool."""
+    width = 30
+    lines: list[str] = []
+
+    lines.append("")
+    lines.append(f"  {term.bold(term.cyan('xsync'))} {term.dim('v' + _version())}")
+    lines.append(
+        term.dim(
+            "  Sync the models of an OpenAI-compatible endpoint into a harness."
+        )
+    )
+    lines.append("")
+
+    for title, rows in HELP_GROUPS:
+        lines.append(f"  {term.bold(title)}")
+        for name, text in rows:
+            lines.append(f"    {term.pad(term.green(name), width)}{term.dim(text)}")
+        lines.append("")
+
+    lines.append(f"  {term.bold('OPTIONS')}")
+    for name, text in HELP_OPTIONS:
+        lines.append(f"    {term.pad(term.yellow(name), width)}{term.dim(text)}")
+    lines.append("")
+
+    lines.append(f"  {term.bold('FILES')}")
+    for name, text in HELP_FILES:
+        lines.append(f"    {term.pad(name, width)}{term.dim(text)}")
+    lines.append("")
+
+    lines.append(f"  {term.bold('EXIT CODES')}")
+    codes = "   ".join(
+        f"{term.bold(code)} {term.dim(text)}" for code, text in HELP_EXIT
+    )
+    lines.append(f"    {codes}")
+    lines.append("")
 
-files:
-  ~/.config/xsync/profiles.toml    the profiles. `xsync setup` writes this file
-  ~/.config/xsync/homes/           one home for each profile and each harness
-  ~/.codex, ~/.claude              only `apply` writes these
+    lines.append(f"  {term.dim('start here:')} {term.bold('xsync setup')}")
+    lines.append("")
+    return "\n".join(lines)
 
-exit codes:
-  0 success    1 error    2 the endpoint does not answer
-"""
 
 
 def cmd_help(args: argparse.Namespace) -> int:
     """Show the help of the tool, or the help of one command."""
     parser = build_parser()
     if not args.topic:
-        parser.print_help()
+        print(render_help())
         return EXIT_OK
 
     actions = [
@@ -841,8 +916,6 @@ def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="xsync",
         description="Sync the model list of an OpenAI-compatible endpoint into a harness.",
-        epilog=EPILOG,
-        formatter_class=argparse.RawDescriptionHelpFormatter,
     )
     sub = parser.add_subparsers(dest="command", metavar="command")
 
@@ -906,7 +979,7 @@ def main(argv: list[str] | None = None) -> int:
     args = parser.parse_args(mine)
     args.extra = theirs
     if not getattr(args, "command", None):
-        parser.print_help()
+        print(render_help())
         return EXIT_OK
     try:
         return args.func(args)

{xsync_cli-0.2.0 → xsync_cli-0.2.1}/tests/test_cli_profiles.py

@@ -194,3 +194,34 @@ def test_the_help_command_can_explain_one_command(capsys):
 def test_the_help_of_an_unknown_command_fails(capsys):
     assert cli.main(["help", "nope"]) == 1
     assert "nope" in capsys.readouterr().err
+
+
+def test_the_help_groups_the_commands(capsys):
+    cli.main([])
+    out = capsys.readouterr().out
+    for group in ("PROFILES", "HARNESSES", "FILES"):
+        assert group in out
+
+
+def test_the_help_names_the_version(capsys):
+    from importlib.metadata import version
+
+    cli.main([])
+    assert version("xsync-cli") in capsys.readouterr().out
+
+
+def test_the_help_shows_every_command(capsys):
+    cli.main([])
+    out = capsys.readouterr().out
+    for name in ("setup", "list", "use", "remove", "codex", "claude", "help"):
+        assert name in out
+
+
+def test_the_help_explains_apply(capsys):
+    cli.main([])
+    assert "apply" in capsys.readouterr().out
+
+
+def test_the_help_holds_no_escape_code_in_a_pipe(capsys):
+    cli.main([])
+    assert "\x1b[" not in capsys.readouterr().out

{xsync_cli-0.2.0 → xsync_cli-0.2.1}/uv.lock

@@ -74,7 +74,7 @@ wheels = [
 
 [[package]]
 name = "xsync-cli"
-version = "0.1.4"
+version = "0.2.0"
 source = { editable = "." }
 dependencies = [
     { name = "tomlkit" },