cdx-manager 0.2.1 → 0.3.3

package/README.md

@@ -6,7 +6,7 @@ If you use AI coding tools at scale ; multiple accounts, multiple providers : yo
 
 One command to launch any session. Zero auth juggling.
 
-[![License](https://img.shields.io/badge/license-MIT-4C8BF5)](LICENSE) ![Version](https://img.shields.io/badge/version-v0.2.1-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.3.3-4C8BF5) ![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)
 
 ---
 
@@ -69,6 +69,38 @@ One command to launch any session. Zero auth juggling.
 
 ### Install
 
+From npm:
+
+```bash
+npm install -g cdx-manager
+```
+
+With pipx:
+
+```bash
+pipx install cdx-manager
+```
+
+With uv:
+
+```bash
+uv tool install cdx-manager
+```
+
+With the standalone GitHub installer:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/AlexAgo83/cdx-manager/main/install.sh | sh
+```
+
+For a specific version:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/AlexAgo83/cdx-manager/main/install.sh | CDX_VERSION=v0.3.3 sh
+```
+
+From source:
+
 ```bash
 git clone <repo>
 cd cdx-manager
@@ -83,18 +115,12 @@ To uninstall:
 make uninstall
 ```
 
-Alternatively, for a non-symlinked global install:
+Alternatively, for a non-symlinked global source install:
 
 ```bash
 npm install -g .
 ```
 
-Once published to npm:
-
-```bash
-npm install -g cdx-manager
-```
-
 ### Environment
 
 By default, `cdx` stores all data under `~/.cdx/`. Override with:

package/changelogs/CHANGELOGS_0_3_0.md

@@ -0,0 +1,32 @@
+# CHANGELOGS_0_3_0
+
+Release date: 2026-04-16
+
+## CDX Manager 0.3.0
+
+CDX Manager 0.3.0 adds Python-native and standalone installation paths in addition to npm.
+
+### Packaging
+
+- Added `pyproject.toml` so the CLI can be installed with `pipx`, `pip`, or `uv tool`.
+- Added the Python console entrypoint `cdx = "src.cli:cli_entry"`.
+- Added `install.sh` for GitHub Release based installs into `~/.local/share/cdx-manager` with a symlink in `~/.local/bin`.
+- Included `install.sh` and `pyproject.toml` in the npm package file list.
+- Documented npm, pipx, uv, curl installer, and source installation paths.
+- Added GitHub Actions automation for PyPI publication when a GitHub Release is published.
+
+### Validation
+
+```bash
+npm run lint
+npm test
+python3 -m venv /tmp/cdx-pyinstall
+/tmp/cdx-pyinstall/bin/pip install --no-build-isolation .
+/tmp/cdx-pyinstall/bin/cdx --version
+npm --cache /tmp/cdx-npm-cache publish --dry-run
+```
+
+### Notes
+
+- PyPI publication is now technically possible, but still requires PyPI credentials and an explicit publish step.
+- The standalone installer defaults to the latest GitHub Release and supports `CDX_VERSION=vX.Y.Z` for pinned installs.

package/changelogs/CHANGELOGS_0_3_1.md

@@ -0,0 +1,27 @@
+# CHANGELOGS_0_3_1
+
+Release date: 2026-04-16
+
+## CDX Manager 0.3.1
+
+CDX Manager 0.3.1 is a release-channel synchronization update.
+
+### Packaging
+
+- Uses npm Trusted Publishing through GitHub Actions OIDC instead of long-lived npm tokens.
+- Keeps npm, PyPI, GitHub Releases, pipx, uv, and the standalone installer aligned on the same release version.
+- Retains the Python-native packaging and standalone install support introduced in 0.3.0.
+
+### Validation
+
+```bash
+npm run lint
+npm test
+npm --cache /tmp/cdx-npm-cache publish --dry-run
+python -m build
+python -m twine check dist/*
+```
+
+### Notes
+
+- This release exists because the npm Trusted Publishing workflow was added after the `v0.3.0` tag. A fresh release is required for GitHub Actions to run the updated workflow definition for npm publishing.

package/changelogs/CHANGELOGS_0_3_2.md

@@ -0,0 +1,21 @@
+# CHANGELOGS_0_3_2
+
+Release date: 2026-04-16
+
+## CDX Manager 0.3.2
+
+CDX Manager 0.3.2 updates the npm release workflow to use the npm CLI version required for Trusted Publishing.
+
+### Packaging
+
+- Runs the npm publish workflow on Node 24.
+- Installs npm 11 before publishing so GitHub Actions OIDC trusted publishing is supported.
+- Keeps npm, PyPI, GitHub Releases, pipx, uv, and the standalone installer aligned on the same release version.
+
+### Validation
+
+```bash
+npm run lint
+npm test
+npm --cache /tmp/cdx-npm-cache publish --dry-run
+```

package/changelogs/CHANGELOGS_0_3_3.md

@@ -0,0 +1,27 @@
+# CHANGELOGS_0_3_3
+
+Release date: 2026-04-16
+
+## CDX Manager 0.3.3
+
+CDX Manager 0.3.3 adds Windows compatibility across the full codebase.
+
+### Windows support
+
+- **Session store locking**: replaced `fcntl.flock` (Unix-only) with `msvcrt.locking` on Windows, with `seek(0)` to ensure consistent byte-range locking.
+- **Signal handling**: guarded `signal.SIGHUP` references behind `hasattr` checks — `SIGHUP` does not exist on Windows.
+- **Profile isolation**: added `_home_env_overrides()` helper that sets `USERPROFILE`, `HOMEDRIVE`, and `HOMEPATH` in addition to `HOME` when launching the `claude` CLI on Windows, so Node.js `os.homedir()` resolves to the correct session profile.
+- **Desktop notifications**: `cdx notify` now sends a notification via PowerShell `System.Windows.Forms.MessageBox` on Windows (falls back silently if PowerShell is unavailable).
+- **ANSI colors**: `cli_entry` enables VT processing via `ctypes.windll.kernel32.SetConsoleMode` on Windows so color output works in terminals that support it.
+- **Console encoding**: `cli_entry` reconfigures `stdout`/`stderr` to UTF-8 on Windows to prevent `UnicodeEncodeError` on non-ASCII session names.
+
+### Maintenance
+
+- Expanded `.gitignore` with standard Python build artifacts (`__pycache__/`, `*.egg-info/`, `dist/`, `build/`), virtual environments, coverage output, and OS-specific files (`.DS_Store`, `Thumbs.db`, `desktop.ini`).
+
+### Validation
+
+```bash
+npm run lint
+npm test
+```

package/install.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env sh
+set -eu
+
+REPO="AlexAgo83/cdx-manager"
+VERSION="${CDX_VERSION:-}"
+PREFIX="${PREFIX:-$HOME/.local}"
+BIN_DIR="${BIN_DIR:-$PREFIX/bin}"
+INSTALL_ROOT="${CDX_INSTALL_ROOT:-$PREFIX/share/cdx-manager}"
+
+need() {
+  if ! command -v "$1" >/dev/null 2>&1; then
+    echo "cdx install: missing required command: $1" >&2
+    exit 1
+  fi
+}
+
+need curl
+need tar
+need python3
+
+if [ -z "$VERSION" ]; then
+  VERSION="$(
+    curl -fsSL "https://api.github.com/repos/$REPO/releases/latest" |
+      python3 -c 'import json, sys; print(json.load(sys.stdin)["tag_name"])'
+  )"
+fi
+
+case "$VERSION" in
+  v*) TAG="$VERSION" ;;
+  *) TAG="v$VERSION" ;;
+esac
+
+TMP_DIR="$(mktemp -d)"
+cleanup() {
+  rm -rf "$TMP_DIR"
+}
+trap cleanup EXIT INT TERM
+
+ARCHIVE_URL="https://github.com/$REPO/archive/refs/tags/$TAG.tar.gz"
+curl -fsSL "$ARCHIVE_URL" -o "$TMP_DIR/cdx-manager.tar.gz"
+tar -xzf "$TMP_DIR/cdx-manager.tar.gz" -C "$TMP_DIR"
+
+SRC_DIR="$(find "$TMP_DIR" -mindepth 1 -maxdepth 1 -type d | head -n 1)"
+TARGET_DIR="$INSTALL_ROOT/${TAG#v}"
+
+mkdir -p "$INSTALL_ROOT" "$BIN_DIR"
+rm -rf "$TARGET_DIR"
+mkdir -p "$TARGET_DIR"
+
+cp -R "$SRC_DIR"/. "$TARGET_DIR"/
+chmod +x "$TARGET_DIR/bin/cdx"
+ln -sfn "$TARGET_DIR/bin/cdx" "$BIN_DIR/cdx"
+
+echo "Installed cdx $TAG to $TARGET_DIR"
+echo "Linked $BIN_DIR/cdx"
+case ":$PATH:" in
+  *":$BIN_DIR:"*) ;;
+  *)
+    echo "Add $BIN_DIR to PATH to run cdx from anywhere." >&2
+    ;;
+esac

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdx-manager",
-  "version": "0.2.1",
+  "version": "0.3.3",
   "description": "Terminal session manager for Codex and Claude accounts.",
   "license": "MIT",
   "author": "Alexandre Agostini",
@@ -27,6 +27,8 @@
     "bin",
     "changelogs",
     "src",
+    "install.sh",
+    "pyproject.toml",
     "README.md",
     "LICENSE"
   ],

package/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cdx-manager"
+version = "0.3.3"
+description = "Terminal session manager for Codex and Claude accounts."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [
+  { name = "Alexandre Agostini" }
+]
+keywords = ["codex", "claude", "cli", "terminal", "session-manager", "ai-tools"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development",
+  "Topic :: Terminals",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/AlexAgo83/cdx-manager"
+Repository = "https://github.com/AlexAgo83/cdx-manager.git"
+Issues = "https://github.com/AlexAgo83/cdx-manager/issues"
+Changelog = "https://github.com/AlexAgo83/cdx-manager/tree/main/changelogs"
+
+[project.scripts]
+cdx = "cdx_manager.cli:cli_entry"
+
+[tool.setuptools]
+packages = ["cdx_manager"]
+
+[tool.setuptools.package-dir]
+cdx_manager = "src"

package/src/cli.py

@@ -39,7 +39,7 @@ from .status_view import (
     _format_status_rows,
 )
 
-VERSION = "0.2.1"
+VERSION = "0.3.3"
 
 
 # ---------------------------------------------------------------------------
@@ -180,9 +180,41 @@ def main(argv, options=None):
     raise CdxError(f"Unknown command: {command}. Use cdx --help.")
 
 
-if __name__ == "__main__":
+def _enable_windows_ansi():
+    if sys.platform != "win32":
+        return
+    try:
+        import ctypes
+        kernel32 = ctypes.windll.kernel32
+        for handle_id in (-10, -11, -12):  # stdin, stdout, stderr
+            handle = kernel32.GetStdHandle(handle_id)
+            mode = ctypes.c_ulong()
+            if kernel32.GetConsoleMode(handle, ctypes.byref(mode)):
+                kernel32.SetConsoleMode(handle, mode.value | 0x0004)
+    except Exception:
+        pass
+
+
+def _configure_windows_encoding():
+    if sys.platform != "win32":
+        return
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            if hasattr(stream, "reconfigure"):
+                stream.reconfigure(encoding="utf-8", errors="replace")
+        except Exception:
+            pass
+
+
+def cli_entry():
+    _enable_windows_ansi()
+    _configure_windows_encoding()
     try:
         raise SystemExit(main(sys.argv[1:]))
     except CdxError as error:
         sys.stderr.write(f"{format_error(error)}\n")
         raise SystemExit(error.exit_code)
+
+
+if __name__ == "__main__":
+    cli_entry()

package/src/notify.py

@@ -114,13 +114,38 @@ def _event(ready, title, message, session_name, target_timestamp=None):
 
 
 def send_desktop_notification(title, message, spawn_sync=None, env=None):
+    import sys
     spawn_sync = spawn_sync or subprocess.run
     env = env or os.environ
-    if shutil_which("osascript", env):
+    if sys.platform == "win32":
+        _send_windows_notification(title, message, spawn_sync, env)
+    elif shutil_which("osascript", env):
         script = f'display notification "{_escape_applescript(message)}" with title "{_escape_applescript(title)}"'
         spawn_sync(["osascript", "-e", script], env=env, capture_output=True, text=True)
 
 
+def _send_windows_notification(title, message, spawn_sync, env):
+    title_escaped = _escape_powershell(title)
+    message_escaped = _escape_powershell(message)
+    script = (
+        "Add-Type -AssemblyName System.Windows.Forms; "
+        f"[System.Windows.Forms.MessageBox]::Show('{message_escaped}', '{title_escaped}')"
+    )
+    try:
+        spawn_sync(
+            ["powershell", "-NoProfile", "-NonInteractive", "-Command", script],
+            env=env,
+            capture_output=True,
+            text=True,
+        )
+    except (FileNotFoundError, OSError):
+        pass
+
+
+def _escape_powershell(value):
+    return str(value).replace("'", "''")
+
+
 def shutil_which(command, env):
     import shutil
     return shutil.which(command, path=env.get("PATH"))

package/src/provider_runtime.py

@@ -3,6 +3,7 @@ import os
 import signal
 import shlex
 import subprocess
+import sys
 from datetime import datetime, timezone
 
 from .errors import CdxError
@@ -11,6 +12,21 @@ from .errors import CdxError
 LOG_ROTATE_BYTES = 10 * 1024 * 1024  # 10 MB
 
 
+def _home_env_overrides(auth_home):
+    """Return env vars that point the claude CLI to the given home directory.
+
+    On Unix, only HOME is needed.  On Windows, Node.js resolves the home
+    directory via USERPROFILE (and falls back to HOMEDRIVE+HOMEPATH), so we
+    set all three to ensure profile isolation works regardless of the platform.
+    """
+    overrides = {"HOME": auth_home}
+    if sys.platform == "win32":
+        overrides["USERPROFILE"] = auth_home
+        overrides["HOMEDRIVE"] = os.path.splitdrive(auth_home)[0] or "C:"
+        overrides["HOMEPATH"] = os.path.splitdrive(auth_home)[1] or auth_home
+    return overrides
+
+
 def _get_auth_home(session):
     return session.get("authHome") or session.get("sessionRoot") or session.get("codexHome", "")
 
@@ -91,7 +107,7 @@ def _build_launch_spec(session, cwd=None, env_override=None):
             "args": ["--name", session["name"]],
             "options": {
                 "cwd": cwd,
-                "env": {**env, "HOME": _get_auth_home(session)},
+                "env": {**env, **_home_env_overrides(_get_auth_home(session))},
             },
             "label": "claude",
         }
@@ -108,7 +124,7 @@ def _build_launch_spec(session, cwd=None, env_override=None):
 def _build_login_status_spec(session, env_override=None):
     env = {**os.environ, **(env_override or {})}
     if session["provider"] == "claude":
-        env["HOME"] = _get_auth_home(session)
+        env.update(_home_env_overrides(_get_auth_home(session)))
 
         def parser(output):
             try:
@@ -133,7 +149,7 @@ def _build_auth_action_spec(session, action, cwd=None, env_override=None):
     cwd = cwd or os.getcwd()
     env = {**os.environ, **(env_override or {})}
     if session["provider"] == "claude":
-        env["HOME"] = _get_auth_home(session)
+        env.update(_home_env_overrides(_get_auth_home(session)))
         return {"command": "claude", "args": ["auth", action],
                 "options": {"cwd": cwd, "env": env}, "label": f"claude auth {action}"}
     env["CODEX_HOME"] = _get_auth_home(session)
@@ -165,7 +181,10 @@ def _probe_provider_auth(session, spawn_sync=None, env_override=None):
 
 
 def _signal_exit_code(sig):
-    return {signal.SIGHUP: 129, signal.SIGINT: 130, signal.SIGTERM: 143}.get(sig, 1)
+    mapping = {signal.SIGINT: 130, signal.SIGTERM: 143}
+    if hasattr(signal, "SIGHUP"):
+        mapping[signal.SIGHUP] = 129
+    return mapping.get(sig, 1)
 
 
 def _run_interactive_provider_command(session, action, spawn=None, cwd=None,
@@ -210,7 +229,10 @@ def _run_interactive_provider_command(session, action, spawn=None, cwd=None,
             handlers.append((sig, handler))
             signal_emitter.on(sig, handler)
     else:
-        for sig in (signal.SIGINT, signal.SIGTERM, signal.SIGHUP):
+        _forward_sigs = [signal.SIGINT, signal.SIGTERM]
+        if hasattr(signal, "SIGHUP"):
+            _forward_sigs.append(signal.SIGHUP)
+        for sig in _forward_sigs:
             try:
                 original_handlers[sig] = signal.signal(sig, forward)
             except (OSError, ValueError):

package/src/session_store.py

@@ -54,23 +54,40 @@ def _fsync_directory(directory):
 
 @contextmanager
 def _file_lock(lock_path):
+    import sys
     _ensure_dir(os.path.dirname(lock_path))
     with open(lock_path, "a", encoding="utf-8") as lock:
-        try:
-            import fcntl
-        except ImportError as error:
-            raise CdxError("Session store locking requires fcntl on this platform") from error
-        try:
-            fcntl.flock(lock.fileno(), fcntl.LOCK_EX)
-        except OSError as error:
-            raise CdxError(f"Failed to lock session store: {error}") from error
-        try:
-            yield
-        finally:
+        if sys.platform == "win32":
+            import msvcrt
+            try:
+                lock.seek(0)
+                msvcrt.locking(lock.fileno(), msvcrt.LK_LOCK, 1)
+            except OSError as error:
+                raise CdxError(f"Failed to lock session store: {error}") from error
+            try:
+                yield
+            finally:
+                try:
+                    lock.seek(0)
+                    msvcrt.locking(lock.fileno(), msvcrt.LK_UNLCK, 1)
+                except OSError as error:
+                    raise CdxError(f"Failed to unlock session store: {error}") from error
+        else:
             try:
-                fcntl.flock(lock.fileno(), fcntl.LOCK_UN)
+                import fcntl
+            except ImportError as error:
+                raise CdxError("Session store locking requires fcntl on this platform") from error
+            try:
+                fcntl.flock(lock.fileno(), fcntl.LOCK_EX)
             except OSError as error:
-                raise CdxError(f"Failed to unlock session store: {error}") from error
+                raise CdxError(f"Failed to lock session store: {error}") from error
+            try:
+                yield
+            finally:
+                try:
+                    fcntl.flock(lock.fileno(), fcntl.LOCK_UN)
+                except OSError as error:
+                    raise CdxError(f"Failed to unlock session store: {error}") from error
 
 
 def create_session_store(base_dir):