cdx-manager 0.4.3 → 0.4.4

package/README.md

@@ -1,6 +1,6 @@
 # CDX Manager
 
-[![License](https://img.shields.io/badge/license-MIT-4C8BF5)](LICENSE) ![Version](https://img.shields.io/badge/version-v0.4.3-4C8BF5) ![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)
+[![License](https://img.shields.io/badge/license-MIT-4C8BF5)](LICENSE) ![Version](https://img.shields.io/badge/version-v0.4.4-4C8BF5) ![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)
 
 **Run multiple Codex and Claude sessions from one terminal. Switch between accounts instantly.**
 
@@ -122,7 +122,7 @@ For a specific version:
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/AlexAgo83/cdx-manager/main/install.sh -o install.sh
-CDX_VERSION=v0.4.3 sh install.sh
+CDX_VERSION=v0.4.4 sh install.sh
 ```
 
 From source:
@@ -143,6 +143,12 @@ npm install -g .
 
 `cdx` is now available globally. Changes to the source take effect immediately — no reinstall needed.
 
+To update an installed copy later:
+
+```bash
+cdx update
+```
+
 To uninstall:
 
 ```bash
@@ -242,6 +248,7 @@ cdx status
 | `cdx import <file> [--sessions a,b] [--passphrase-env VAR] [--force] [--json]` | Import sessions from a bundle into the current `CDX_HOME` |
 | `cdx doctor [--json]` | Inspect CLI dependencies, CDX_HOME permissions, missing state, orphan profiles, and pending quarantines |
 | `cdx repair [--dry-run] [--force] [--json]` | Plan or apply safe repairs for missing state files, quarantines, and orphan profiles |
+| `cdx update [--check] [--yes] [--json] [--version TAG]` | Update cdx-manager using the installer that matches how it was installed |
 | `cdx notify <name> --at-reset [--poll seconds] [--once] [--json]` | Wait for a session reset time and send a desktop notification when due |
 | `cdx notify --next-ready [--poll seconds] [--once] [--json]` | Wait until the recommended session is usable or needs a refresh after reset |
 | `cdx status [--json] [--refresh]` | Show token usage table for all sessions; JSON returns a versioned payload with structured warnings |
@@ -272,6 +279,7 @@ Commands with machine-readable output:
 - `cdx logout ... --json`
 - `cdx doctor --json`
 - `cdx repair --json`
+- `cdx update --json`
 - `cdx notify ... --json`
 
 Success payloads follow a shared envelope:

package/changelogs/CHANGELOGS_0_4_4.md

@@ -0,0 +1,33 @@
+# Changelog (`0.4.3 -> 0.4.4`)
+
+Release date: 2026-04-20
+
+## Major Highlights
+
+- Generated from the release work on `cdx update`, the first built-in self-update path for `cdx-manager`.
+- Added a version-aware update command that can check for a newer release, confirm interactively, and delegate to the right installer for the current installation type.
+- Kept the existing update warning behavior intact so the CLI still surfaces newer releases on startup.
+- Reserved `update` as a session name to avoid collisions with the new command.
+
+## `cdx update`
+
+- Added `cdx update --check` for a quick release check without applying changes.
+- Added `cdx update --yes` for non-interactive environments.
+- Added `cdx update --version TAG` so maintainers can target a specific release.
+- Routed standalone installs through `install.sh` / `install.ps1`.
+- Routed npm installs through `npm install -g cdx-manager@...`.
+- Routed Python environment installs through `python -m pip install --upgrade ...`.
+- Routed source checkouts through `git pull --ff-only` or an explicit tag checkout when a version is requested.
+- Refused source updates when the checkout contains uncommitted changes.
+
+## Validation and Regression Coverage
+
+- Added CLI coverage for update checks, update execution, and version-aware help text.
+- Added session-service coverage for the new reserved command name.
+- Added unit coverage for installation detection and source-checkout safety in the update planner.
+- Kept the existing CLI and session-service test suites green.
+
+## Validation and Regression Evidence
+
+- `python3 -m unittest test.test_cli_py test.test_session_service_py test.test_update_manager_py`
+- `npm run lint`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdx-manager",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "description": "Terminal session manager for Codex and Claude accounts.",
   "license": "MIT",
   "author": "Alexandre Agostini",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cdx-manager"
-version = "0.4.3"
+version = "0.4.4"
 description = "Terminal session manager for Codex and Claude accounts."
 readme = "README.md"
 requires-python = ">=3.9"

package/src/cli.py

@@ -21,6 +21,7 @@ from .cli_commands import (
     handle_repair,
     handle_rename,
     handle_status,
+    handle_update,
 )
 from .cli_render import (
     _format_sessions,
@@ -44,7 +45,7 @@ from .status_view import (
 )
 from .update_check import check_for_update
 
-VERSION = "0.4.3"
+VERSION = "0.4.4"
 
 
 # ---------------------------------------------------------------------------
@@ -72,6 +73,7 @@ def _print_help(use_color=False):
         f"  {_style('cdx import <file> [--sessions a,b] [--passphrase-env VAR] [--force] [--json]', '36', use_color)}",
         f"  {_style('cdx doctor [--json]', '36', use_color)}",
         f"  {_style('cdx repair [--dry-run] [--force] [--json]', '36', use_color)}",
+        f"  {_style('cdx update [--check] [--yes] [--json] [--version TAG]', '36', use_color)}",
         f"  {_style('cdx notify <name> --at-reset [--json]', '36', use_color)}",
         f"  {_style('cdx notify --next-ready [--json]', '36', use_color)}",
         f"  {_style('cdx <name> [--json]', '36', use_color)}",
@@ -205,8 +207,9 @@ def main(argv, options=None):
         "spawn": spawn,
         "spawn_sync": spawn_sync,
         "stdin_is_tty": stdin_is_tty,
+        "version": VERSION,
         "update_notice": _get_update_notice(service, env, options) if command not in (
-            "add", "cp", "ren", "rename", "mv", "rmv", "clean", "doctor", "repair", "notify", "status", "login", "logout", "export", "import", "help", "version"
+            "add", "cp", "ren", "rename", "mv", "rmv", "clean", "doctor", "repair", "update", "notify", "status", "login", "logout", "export", "import", "help", "version"
         ) else None,
         "use_color": use_color,
     }
@@ -238,6 +241,9 @@ def main(argv, options=None):
     if command == "repair":
         return handle_repair(rest, ctx)
 
+    if command == "update":
+        return handle_update(rest, ctx)
+
     if command == "notify":
         return handle_notify(rest, ctx)
 

package/src/cli_commands.py

@@ -22,11 +22,14 @@ from .provider_runtime import (
 from .repair import format_repair_report, repair_health
 from .backup_bundle import read_bundle_meta
 from .status_view import _format_status_detail, _format_status_rows
+from .update_check import fetch_latest_release, is_newer_version
+from .update_manager import build_update_plan, format_update_failure, run_update_plan
 
 
 STATUS_USAGE = "Usage: cdx status [--json] [--refresh] | cdx status --small|-s [--refresh] | cdx status <name> [--json] [--refresh]"
 DOCTOR_USAGE = "Usage: cdx doctor [--json]"
 REPAIR_USAGE = "Usage: cdx repair [--dry-run] [--force] [--json]"
+UPDATE_USAGE = "Usage: cdx update [--check] [--yes] [--json] [--version TAG]"
 EXPORT_USAGE = "Usage: cdx export <file> [--include-auth] [--force] [--json] [--sessions name1,name2] [--passphrase-env VAR]"
 IMPORT_USAGE = "Usage: cdx import <file> [--force] [--json] [--sessions name1,name2] [--passphrase-env VAR]"
 API_SCHEMA_VERSION = 1
@@ -102,6 +105,45 @@ def _parse_session_names(value):
     return names
 
 
+def _parse_update_args(args):
+    parsed = {
+        "check": False,
+        "json": False,
+        "yes": False,
+        "version": None,
+    }
+    index = 0
+    while index < len(args):
+        arg = args[index]
+        if arg == "--check":
+            parsed["check"] = True
+            index += 1
+            continue
+        if arg == "--json":
+            parsed["json"] = True
+            index += 1
+            continue
+        if arg == "--yes":
+            parsed["yes"] = True
+            index += 1
+            continue
+        if arg == "--version":
+            value, index = _read_option_value(args, index, UPDATE_USAGE)
+            parsed["version"] = value
+            continue
+        if arg.startswith("--version="):
+            parsed["version"] = arg.split("=", 1)[1]
+            index += 1
+            continue
+        raise CdxError(UPDATE_USAGE)
+
+    if parsed["check"] and parsed["version"]:
+        raise CdxError("Usage: cdx update --check cannot be combined with --version.")
+    if parsed["version"] is not None and not parsed["version"].strip():
+        raise CdxError("Usage: cdx update [--check] [--yes] [--json] [--version TAG]")
+    return parsed
+
+
 def _parse_export_args(args):
     parsed = {
         "file_path": None,
@@ -649,6 +691,91 @@ def handle_logout(rest, ctx):
     return 0
 
 
+def handle_update(rest, ctx):
+    parsed = _parse_update_args(rest)
+    json_flag = parsed["json"]
+    current_version = str(ctx.get("version") or "").strip()
+    release_fetcher = ctx["options"].get("fetchLatestRelease") or fetch_latest_release
+    target_version = None
+    release_url = None
+    update_available = False
+
+    if parsed["version"] is not None:
+        target_version = str(parsed["version"]).strip().lstrip("v")
+    else:
+        latest = release_fetcher()
+        if not latest:
+            raise CdxError("Unable to check for the latest cdx-manager release. Check your network and try again.")
+        target_version = str(latest.get("latest_version") or "").strip()
+        release_url = latest.get("url")
+        if not target_version:
+            raise CdxError("Unable to determine the latest cdx-manager release.")
+        update_available = is_newer_version(current_version, target_version)
+        if parsed["check"] or not update_available:
+            message = (
+                f"Update available: cdx-manager {target_version} (current {current_version})"
+                if update_available
+                else f"cdx-manager {current_version} is already up to date."
+            )
+            if json_flag:
+                _write_json(ctx, _json_success(
+                    "update",
+                    message,
+                    checked=True,
+                    update_available=update_available,
+                    current_version=current_version,
+                    target_version=target_version,
+                    release_url=release_url,
+                    warnings=[{
+                        "code": "update_available",
+                        "message": message,
+                        "latest_version": target_version,
+                        "url": release_url,
+                    }] if update_available else [],
+                ))
+                return 0
+            ctx["out"](f"{_warn(message, ctx['use_color']) if update_available else _success(message, ctx['use_color'])}\n")
+            return 0
+
+    if not parsed["yes"]:
+        if not ctx["stdin_is_tty"]:
+            raise CdxError("Update requires an interactive terminal or --yes in non-interactive mode.")
+        answer = input(f"Update cdx-manager to {target_version}? [y/N] ")
+        if answer.strip().lower() not in ("y", "yes"):
+            message = "Cancelled."
+            if json_flag:
+                _write_json(ctx, _json_success("update", message, cancelled=True, current_version=current_version, target_version=target_version))
+                return 0
+            ctx["out"](f"{_warn(message, ctx['use_color'])}\n")
+            return 0
+
+    plan = build_update_plan(
+        target_version=target_version,
+        package_root=ctx["options"].get("packageRoot"),
+        prefix=ctx["options"].get("prefix"),
+        base_prefix=ctx["options"].get("basePrefix"),
+    )
+    results = run_update_plan(plan, runner=ctx["options"].get("runUpdate"), env=ctx.get("env"))
+    failed = any((result.get("returncode") not in (0, None)) for result in results)
+    if failed:
+        raise CdxError(format_update_failure(results))
+
+    message = f"Updated cdx-manager to {target_version}"
+    if json_flag:
+        _write_json(ctx, _json_success(
+            "update",
+            message,
+            updated=True,
+            current_version=current_version,
+            target_version=target_version,
+            mode=plan["mode"],
+            steps=results,
+        ))
+        return 0
+    ctx["out"](f"{_success(message, ctx['use_color'])}\n")
+    return 0
+
+
 def handle_launch(command, ctx):
     json_flag = "--json" in ctx["options"].get("raw_args", [])
     update_notice = ctx.get("update_notice")

package/src/session_service.py

@@ -33,6 +33,7 @@ RESERVED_SESSION_NAMES = {
     "rename",
     "rmv",
     "status",
+    "update",
     "version",
     "--help",
     "-h",

package/src/update_check.py

@@ -28,6 +28,10 @@ def _is_newer_version(current_version, latest_version):
     return latest > current
 
 
+def is_newer_version(current_version, latest_version):
+    return _is_newer_version(current_version, latest_version)
+
+
 def _cache_path(base_dir):
     return os.path.join(base_dir, "state", "update-check.json")
 
@@ -63,6 +67,13 @@ def _fetch_latest_release():
     }
 
 
+def fetch_latest_release():
+    try:
+        return _fetch_latest_release()
+    except (urllib.error.URLError, TimeoutError, ValueError, OSError):
+        return None
+
+
 def check_for_update(base_dir, current_version, env=None, now_fn=None):
     env = env or os.environ
     now_fn = now_fn or (lambda: datetime.now(timezone.utc).timestamp())
@@ -83,9 +94,8 @@ def check_for_update(base_dir, current_version, env=None, now_fn=None):
             }
         return None
 
-    try:
-        latest = _fetch_latest_release()
-    except (urllib.error.URLError, TimeoutError, ValueError, OSError):
+    latest = fetch_latest_release()
+    if not latest:
         return None
 
     payload = {

package/src/update_manager.py

@@ -0,0 +1,208 @@
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from .errors import CdxError
+
+
+def _package_root(path=None):
+    if path is not None:
+        return Path(path).resolve()
+    return Path(__file__).resolve().parents[1]
+
+
+def _normalize_version(value):
+    if value is None:
+        return None
+    text = str(value).strip()
+    if not text:
+        return None
+    return text.lstrip("v")
+
+
+def _is_standalone_install(package_root):
+    return package_root.parent.name == "versions"
+
+
+def _is_source_checkout(package_root):
+    return (package_root / ".git").exists()
+
+
+def _is_git_dirty(package_root):
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(package_root), "status", "--porcelain"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except FileNotFoundError as error:
+        raise CdxError("git is required to update a source checkout.") from error
+    return bool((result.stdout or "").strip())
+
+
+def _is_python_env(prefix=None, base_prefix=None):
+    prefix = prefix or sys.prefix
+    base_prefix = base_prefix or sys.base_prefix
+    return prefix != base_prefix
+
+
+def detect_installation(package_root=None, prefix=None, base_prefix=None):
+    root = _package_root(package_root)
+    if _is_standalone_install(root):
+        return {"mode": "standalone", "package_root": str(root)}
+    if _is_source_checkout(root):
+        return {"mode": "source", "package_root": str(root)}
+    if _is_python_env(prefix=prefix, base_prefix=base_prefix):
+        return {"mode": "python", "package_root": str(root)}
+    if (root / "package.json").exists():
+        return {"mode": "npm", "package_root": str(root)}
+    return {"mode": "unknown", "package_root": str(root)}
+
+
+def _join_command(*parts):
+    return [str(part) for part in parts if part is not None]
+
+
+def _build_standalone_step(package_root, target_version):
+    package_root = _package_root(package_root)
+    env = {}
+    if target_version:
+        env["CDX_VERSION"] = target_version
+    if sys.platform == "win32":
+        return {
+            "label": "standalone installer",
+            "command": _join_command("powershell", "-ExecutionPolicy", "Bypass", "-File", package_root / "install.ps1"),
+            "cwd": str(package_root),
+            "env": env,
+        }
+    return {
+        "label": "standalone installer",
+        "command": _join_command("sh", package_root / "install.sh"),
+        "cwd": str(package_root),
+        "env": env,
+    }
+
+
+def _build_source_steps(package_root, target_version):
+    package_root = _package_root(package_root)
+    if _is_git_dirty(package_root):
+        raise CdxError(
+            "Your source checkout has uncommitted changes. "
+            "Commit or stash them before running cdx update."
+        )
+    if target_version:
+        return [
+            {
+                "label": "fetch tags",
+                "command": _join_command("git", "-C", package_root, "fetch", "--tags", "--force"),
+                "cwd": str(package_root),
+                "env": {},
+            },
+            {
+                "label": f"checkout v{target_version}",
+                "command": _join_command("git", "-C", package_root, "checkout", f"v{target_version}"),
+                "cwd": str(package_root),
+                "env": {},
+            },
+        ]
+    return [
+        {
+            "label": "git pull --ff-only",
+            "command": _join_command("git", "-C", package_root, "pull", "--ff-only"),
+            "cwd": str(package_root),
+            "env": {},
+        }
+    ]
+
+
+def _build_python_step(target_version):
+    command = [sys.executable, "-m", "pip", "install", "--upgrade"]
+    if target_version:
+        command.append(f"cdx-manager=={target_version}")
+    else:
+        command.append("cdx-manager")
+    return {
+        "label": "python package upgrade",
+        "command": command,
+        "cwd": None,
+        "env": {},
+    }
+
+
+def _build_npm_step(target_version):
+    spec = f"cdx-manager@{target_version}" if target_version else "cdx-manager@latest"
+    return {
+        "label": "npm global upgrade",
+        "command": ["npm", "install", "-g", spec],
+        "cwd": None,
+        "env": {},
+    }
+
+
+def build_update_plan(target_version=None, package_root=None, env=None, prefix=None, base_prefix=None):
+    root = _package_root(package_root)
+    version = _normalize_version(target_version)
+    detection = detect_installation(root, prefix=prefix, base_prefix=base_prefix)
+    mode = detection["mode"]
+    if mode == "standalone":
+        steps = [_build_standalone_step(root, version)]
+    elif mode == "source":
+        steps = _build_source_steps(root, version)
+    elif mode == "python":
+        steps = [_build_python_step(version)]
+    elif mode == "npm":
+        steps = [_build_npm_step(version)]
+    else:
+        raise CdxError(
+            "Unable to determine how cdx-manager was installed. "
+            "Set CDX_UPDATE_METHOD or update it manually."
+        )
+    return {
+        "mode": mode,
+        "package_root": str(root),
+        "target_version": version,
+        "steps": steps,
+    }
+
+
+def _result_code(result):
+    if isinstance(result, dict):
+        return result.get("returncode") if result.get("returncode") is not None else result.get("status")
+    return getattr(result, "returncode", getattr(result, "status", None))
+
+
+def _result_text(result, attr):
+    if isinstance(result, dict):
+        return result.get(attr)
+    return getattr(result, attr, "")
+
+
+def run_update_plan(plan, runner=None, env=None):
+    runner = runner or subprocess.run
+    results = []
+    for step in plan["steps"]:
+        step_env = {**(env or os.environ), **(step.get("env") or {})}
+        kwargs = {"cwd": step.get("cwd"), "env": step_env, "check": False}
+        result = runner(step["command"], **kwargs)
+        code = _result_code(result)
+        results.append({
+            "label": step["label"],
+            "command": step["command"],
+            "cwd": step.get("cwd"),
+            "returncode": code,
+            "stdout": _result_text(result, "stdout"),
+            "stderr": _result_text(result, "stderr"),
+        })
+        if code not in (0, None):
+            break
+    return results
+
+
+def format_update_failure(results):
+    if not results:
+        return "Update failed."
+    last = results[-1]
+    message = last.get("stderr") or last.get("stdout") or "Update failed."
+    return f"{last['label']} failed: {str(message).strip()}"