cdx-manager 0.5.3 → 0.5.5

package/src/cli_commands.py

@@ -7,6 +7,7 @@ from datetime import datetime
 
 from .claude_refresh import _refresh_claude_sessions
 from .cli_render import _dim, _info, _success, _warn
+from .config import PROVIDER_CODEX
 from .context_store import (
     clear_context,
     edit_context,
@@ -68,6 +69,76 @@ def _write_json(ctx, payload):
     ctx["out"](f"{json.dumps(payload, indent=2)}\n")
 
 
+def _format_bytes(value):
+    if value is None:
+        return "n/a"
+    try:
+        amount = float(value)
+    except (TypeError, ValueError):
+        return str(value)
+    units = ["B", "KB", "MB", "GB", "TB"]
+    unit = units[0]
+    for unit in units:
+        if amount < 1024 or unit == units[-1]:
+            break
+        amount /= 1024
+    if unit == "B":
+        return f"{int(amount)} B"
+    return f"{amount:.1f} {unit}"
+
+
+def _format_export_report(result):
+    lines = [
+        f"Path: {result['path']}",
+        f"Sessions: {', '.join(result['session_names']) or '-'}",
+        f"Auth: {'included and encrypted' if result['include_auth'] else 'not included'}",
+        f"Bundle size: {_format_bytes(result.get('bundle_size_bytes'))}",
+    ]
+    if result.get("include_auth"):
+        lines.extend([
+            f"Auth files: {result.get('profile_file_count', 0)}",
+            f"Auth data: {_format_bytes(result.get('profile_bytes'))}",
+        ])
+    return "\n".join(lines)
+
+
+def _make_export_progress(ctx):
+    def progress(event):
+        kind = event.get("event")
+        if kind == "export_started":
+            auth = " with auth" if event.get("include_auth") else ""
+            message = f"Exporting {event.get('session_count', 0)} session(s){auth}..."
+            ctx["out"](f"{_info(message, ctx['use_color'])}\n")
+        elif kind == "session_started":
+            message = f"Collecting {event.get('session_name')}..."
+            ctx["out"](f"{_dim(message, ctx['use_color'])}\n")
+        elif kind == "profile_progress":
+            message = f"  {event.get('session_name')}: {event.get('file_count', 0)} files, {_format_bytes(event.get('bytes'))}"
+            ctx["out"](f"{_dim(message, ctx['use_color'])}\n")
+        elif kind == "encoding_started":
+            ctx["out"](f"{_dim('Encoding and encrypting bundle...', ctx['use_color'])}\n")
+        elif kind == "writing_started":
+            message = f"Writing {_format_bytes(event.get('bundle_size_bytes'))}..."
+            ctx["out"](f"{_dim(message, ctx['use_color'])}\n")
+    return progress
+
+
+def _make_status_progress(ctx):
+    def progress(event):
+        kind = event.get("event")
+        if kind == "status_started":
+            message = f"Resolving status for {event.get('session_count', 0)} session(s)..."
+            ctx["out"](f"{_info(message, ctx['use_color'])}\n")
+        elif kind == "session_started":
+            provider = event.get("provider") or "session"
+            message = f"Checking {event.get('session_name')} ({provider})..."
+            ctx["out"](f"{_dim(message, ctx['use_color'])}\n")
+        elif kind == "status_finished":
+            message = f"Resolved {event.get('row_count', 0)} status row(s)."
+            ctx["out"](f"{_dim(message, ctx['use_color'])}\n")
+    return progress
+
+
 def _latest_launch_transcript_path(session):
     paths = _list_launch_transcript_paths(session)
     if not paths:
@@ -112,7 +183,7 @@ def _build_handoff_context(source, target, transcript_path, transcript, truncate
 
 
 def _handoff_launch_prompt(session, install=None):
-    if session.get("provider") == "codex":
+    if session.get("provider") == PROVIDER_CODEX:
         context_ref = "$CODEX_HOME/shared-context.md"
     else:
         context_ref = (install or {}).get("target_path") or os.path.join(
@@ -131,11 +202,54 @@ def _parse_json_flag(args):
     return json_flag, cleaned
 
 
+def _parse_flag_args(args, schema, usage, positionals_key=None, max_positionals=0):
+    parsed = {spec["key"]: spec.get("default") for spec in schema.values()}
+    positionals = []
+    index = 0
+    while index < len(args):
+        arg = args[index]
+        if arg in schema:
+            spec = schema[arg]
+            if spec["type"] == "bool":
+                parsed[spec["key"]] = True
+                index += 1
+                continue
+            value, index = _read_option_value(args, index, usage)
+            parsed[spec["key"]] = spec.get("transform", lambda item: item)(value)
+            continue
+        if arg.startswith("--") and "=" in arg:
+            flag, value = arg.split("=", 1)
+            spec = schema.get(flag)
+            if not spec or spec["type"] == "bool":
+                raise CdxError(usage)
+            parsed[spec["key"]] = spec.get("transform", lambda item: item)(value)
+            index += 1
+            continue
+        if arg.startswith("-"):
+            raise CdxError(usage)
+        positionals.append(arg)
+        if len(positionals) > max_positionals:
+            raise CdxError(usage)
+        index += 1
+
+    if positionals_key is not None:
+        parsed[positionals_key] = positionals
+    return parsed
+
+
 def _parse_add_args(args):
-    if len(args) == 1:
-        return {"provider": "codex", "name": args[0]}
-    if len(args) == 2:
-        return {"provider": args[0], "name": args[1]}
+    parsed = _parse_flag_args(
+        args,
+        {},
+        "Usage: cdx add [provider] <name> [--json]",
+        positionals_key="values",
+        max_positionals=2,
+    )
+    values = parsed["values"]
+    if len(values) == 1:
+        return {"provider": PROVIDER_CODEX, "name": values[0]}
+    if len(values) == 2:
+        return {"provider": values[0], "name": values[1]}
     raise CdxError("Usage: cdx add [provider] <name> [--json]")
 
 
@@ -152,19 +266,21 @@ def _parse_rename_args(args):
 
 
 def _parse_remove_args(args):
-    force = "--force" in args
-    names = [a for a in args if a != "--force"]
-    unknown = [a for a in args if a.startswith("-") and a != "--force"]
-    if unknown or len(names) != 1 or len(args) > 2:
+    parsed = _parse_flag_args(args, {
+        "--force": {"key": "force", "type": "bool", "default": False},
+    }, "Usage: cdx rmv <name> [--force] [--json]", positionals_key="names", max_positionals=1)
+    if len(parsed["names"]) != 1:
         raise CdxError("Usage: cdx rmv <name> [--force] [--json]")
-    return {"name": names[0], "force": force}
+    return {"name": parsed["names"][0], "force": parsed["force"]}
 
 
 def _parse_toggle_args(args, usage):
-    json_flag, cleaned = _parse_json_flag(args)
-    if len(cleaned) != 1:
+    parsed = _parse_flag_args(args, {
+        "--json": {"key": "json", "type": "bool", "default": False},
+    }, usage, positionals_key="names", max_positionals=1)
+    if len(parsed["names"]) != 1:
         raise CdxError(usage)
-    return {"name": cleaned[0], "json": json_flag}
+    return {"name": parsed["names"][0], "json": parsed["json"]}
 
 
 def _read_option_value(args, index, usage):
@@ -183,37 +299,12 @@ def _parse_session_names(value):
 
 
 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)
-
+    parsed = _parse_flag_args(args, {
+        "--check": {"key": "check", "type": "bool", "default": False},
+        "--json": {"key": "json", "type": "bool", "default": False},
+        "--yes": {"key": "yes", "type": "bool", "default": False},
+        "--version": {"key": "version", "type": "str", "default": None},
+    }, 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():
@@ -222,52 +313,19 @@ def _parse_update_args(args):
 
 
 def _parse_export_args(args):
-    parsed = {
-        "file_path": None,
-        "include_auth": False,
-        "force": False,
-        "json": False,
-        "session_names": None,
-        "passphrase_env": None,
-    }
-    index = 0
-    while index < len(args):
-        arg = args[index]
-        if arg == "--include-auth":
-            parsed["include_auth"] = True
-            index += 1
-            continue
-        if arg == "--force":
-            parsed["force"] = True
-            index += 1
-            continue
-        if arg == "--json":
-            parsed["json"] = True
-            index += 1
-            continue
-        if arg == "--sessions":
-            value, index = _read_option_value(args, index, EXPORT_USAGE)
-            parsed["session_names"] = _parse_session_names(value)
-            continue
-        if arg.startswith("--sessions="):
-            parsed["session_names"] = _parse_session_names(arg.split("=", 1)[1])
-            index += 1
-            continue
-        if arg == "--passphrase-env":
-            value, index = _read_option_value(args, index, EXPORT_USAGE)
-            parsed["passphrase_env"] = value
-            continue
-        if arg.startswith("--passphrase-env="):
-            parsed["passphrase_env"] = arg.split("=", 1)[1]
-            index += 1
-            continue
-        if arg.startswith("-"):
-            raise CdxError(EXPORT_USAGE)
-        if parsed["file_path"] is not None:
-            raise CdxError(EXPORT_USAGE)
-        parsed["file_path"] = arg
-        index += 1
-
+    parsed = _parse_flag_args(args, {
+        "--include-auth": {"key": "include_auth", "type": "bool", "default": False},
+        "--force": {"key": "force", "type": "bool", "default": False},
+        "--json": {"key": "json", "type": "bool", "default": False},
+        "--sessions": {
+            "key": "session_names",
+            "type": "str",
+            "default": None,
+            "transform": _parse_session_names,
+        },
+        "--passphrase-env": {"key": "passphrase_env", "type": "str", "default": None},
+    }, EXPORT_USAGE, positionals_key="positionals", max_positionals=1)
+    parsed["file_path"] = parsed.pop("positionals")[0] if parsed["positionals"] else None
     if not parsed["file_path"]:
         raise CdxError(EXPORT_USAGE)
     if parsed["passphrase_env"] and not parsed["include_auth"]:
@@ -276,47 +334,18 @@ def _parse_export_args(args):
 
 
 def _parse_import_args(args):
-    parsed = {
-        "file_path": None,
-        "force": False,
-        "json": False,
-        "session_names": None,
-        "passphrase_env": None,
-    }
-    index = 0
-    while index < len(args):
-        arg = args[index]
-        if arg == "--force":
-            parsed["force"] = True
-            index += 1
-            continue
-        if arg == "--json":
-            parsed["json"] = True
-            index += 1
-            continue
-        if arg == "--sessions":
-            value, index = _read_option_value(args, index, IMPORT_USAGE)
-            parsed["session_names"] = _parse_session_names(value)
-            continue
-        if arg.startswith("--sessions="):
-            parsed["session_names"] = _parse_session_names(arg.split("=", 1)[1])
-            index += 1
-            continue
-        if arg == "--passphrase-env":
-            value, index = _read_option_value(args, index, IMPORT_USAGE)
-            parsed["passphrase_env"] = value
-            continue
-        if arg.startswith("--passphrase-env="):
-            parsed["passphrase_env"] = arg.split("=", 1)[1]
-            index += 1
-            continue
-        if arg.startswith("-"):
-            raise CdxError(IMPORT_USAGE)
-        if parsed["file_path"] is not None:
-            raise CdxError(IMPORT_USAGE)
-        parsed["file_path"] = arg
-        index += 1
-
+    parsed = _parse_flag_args(args, {
+        "--force": {"key": "force", "type": "bool", "default": False},
+        "--json": {"key": "json", "type": "bool", "default": False},
+        "--sessions": {
+            "key": "session_names",
+            "type": "str",
+            "default": None,
+            "transform": _parse_session_names,
+        },
+        "--passphrase-env": {"key": "passphrase_env", "type": "str", "default": None},
+    }, IMPORT_USAGE, positionals_key="positionals", max_positionals=1)
+    parsed["file_path"] = parsed.pop("positionals")[0] if parsed["positionals"] else None
     if not parsed["file_path"]:
         raise CdxError(IMPORT_USAGE)
     return parsed
@@ -558,21 +587,20 @@ def handle_doctor(rest, ctx):
 
 
 def handle_repair(rest, ctx):
-    json_flag = "--json" in rest
-    dry_run = "--dry-run" in rest or "--force" not in rest
-    force = "--force" in rest
-    allowed = {"--json", "--dry-run", "--force"}
-    unknown = [arg for arg in rest if arg not in allowed]
-    if unknown:
-        raise CdxError(REPAIR_USAGE)
+    parsed = _parse_flag_args(rest, {
+        "--json": {"key": "json", "type": "bool", "default": False},
+        "--dry-run": {"key": "dry_run", "type": "bool", "default": False},
+        "--force": {"key": "force", "type": "bool", "default": False},
+    }, REPAIR_USAGE)
+    dry_run = parsed["dry_run"] or not parsed["force"]
     report = repair_health(
         ctx["service"],
         ctx["service"]["base_dir"],
         env=ctx.get("env"),
         dry_run=dry_run,
-        force=force,
+        force=parsed["force"],
     )
-    if json_flag:
+    if parsed["json"]:
         _write_json(ctx, _json_success("repair", "Collected repair report", report=report))
     else:
         ctx["out"](f"{format_repair_report(report, use_color=ctx['use_color'])}\n")
@@ -704,22 +732,23 @@ def handle_context(rest, ctx):
 
 
 def handle_status(rest, ctx):
-    json_flag = "--json" in rest
-    small_flag = "--small" in rest or "-s" in rest
-    refresh_flag = "--refresh" in rest
-    status_flags = {"--json", "--small", "-s", "--refresh"}
-    args = [a for a in rest if a not in status_flags]
-    unknown_flags = [a for a in args if a.startswith("-")]
-    if unknown_flags or (json_flag and small_flag):
+    parsed = _parse_flag_args(rest, {
+        "--json": {"key": "json", "type": "bool", "default": False},
+        "--small": {"key": "small", "type": "bool", "default": False},
+        "-s": {"key": "small", "type": "bool", "default": False},
+        "--refresh": {"key": "refresh", "type": "bool", "default": False},
+    }, STATUS_USAGE, positionals_key="args", max_positionals=1)
+    if parsed["json"] and parsed["small"]:
         raise CdxError(STATUS_USAGE)
-    if len(args) > 1 or (len(args) == 1 and small_flag):
+    args = parsed["args"]
+    if len(args) == 1 and parsed["small"]:
         raise CdxError(STATUS_USAGE)
 
     refresh_result = _refresh_claude_sessions(
         ctx["service"],
         ctx.get("refresh_fn"),
         target_names=args if len(args) == 1 else None,
-        force=refresh_flag,
+        force=parsed["refresh"],
     )
     refresh_errors = [
         {
@@ -737,19 +766,20 @@ def handle_status(rest, ctx):
         for item in refresh_errors
     ]
 
-    rows = ctx["service"]["get_status_rows"]()
+    status_progress = None if parsed["json"] else _make_status_progress(ctx)
+    rows = ctx["service"]["get_status_rows"](progress_callback=status_progress)
     if len(args) == 0:
-        if json_flag:
+        if parsed["json"]:
             _write_json(ctx, _json_success("status", "Collected session status rows", warnings=warnings, rows=rows))
             return 0
-        ctx["out"](f"{_format_status_rows(rows, use_color=ctx['use_color'], small=small_flag)}\n")
+        ctx["out"](f"{_format_status_rows(rows, use_color=ctx['use_color'], small=parsed['small'])}\n")
         _write_refresh_warnings(refresh_errors, ctx)
         return 0
 
     row = next((r for r in rows if r["session_name"] == args[0]), None)
     if not row:
         raise CdxError(f"Unknown session: {args[0]}")
-    if json_flag:
+    if parsed["json"]:
         _write_json(ctx, _json_success("status", f"Collected status for {args[0]}", warnings=warnings, session=row))
         return 0
     ctx["out"](f"{_format_status_detail(row, use_color=ctx['use_color'])}\n")
@@ -781,6 +811,7 @@ def handle_export(rest, ctx):
         session_names=parsed["session_names"],
         passphrase=passphrase,
         force=parsed["force"],
+        progress_callback=None if parsed["json"] else _make_export_progress(ctx),
     )
     session_count = len(result["session_names"])
     auth_suffix = " with auth" if result["include_auth"] else ""
@@ -794,6 +825,7 @@ def handle_export(rest, ctx):
         _write_json(ctx, payload)
         return 0
     ctx["out"](f"{_success(message, ctx['use_color'])}\n")
+    ctx["out"](f"{_format_export_report(result)}\n")
     return 0
 
 
@@ -1002,9 +1034,6 @@ def handle_launch(command, ctx, initial_prompt=None):
             if update_notice.get("url"):
                 text = f"{text} {update_notice['url']}"
             ctx["out"](f"{_warn(text, ctx['use_color'])}\n")
-    if session["provider"] == "codex":
-        if not json_flag:
-            ctx["out"](f"{_dim('Tip: cdx status reads Codex rate limits from the local app-server when available.', ctx['use_color'])}\n")
     _run_interactive_provider_command(
         session, "launch", spawn=ctx.get("spawn"), env_override=ctx.get("env"),
         signal_emitter=ctx.get("signal_emitter"), initial_prompt=initial_prompt,

package/src/codex_usage.py

@@ -106,10 +106,10 @@ def _write_json_line(process, payload):
     process.stdin.flush()
 
 
-def fetch_codex_rate_limits(session, timeout=5, popen_factory=None):
+def fetch_codex_rate_limit_diagnostic(session, timeout=5, popen_factory=None):
     auth_home = session.get("authHome")
     if not auth_home:
-        return None
+        return {"ok": False, "reason": "missing_auth_home", "status": None}
 
     env = os.environ.copy()
     env["CODEX_HOME"] = auth_home
@@ -139,7 +139,12 @@ def fetch_codex_rate_limits(session, timeout=5, popen_factory=None):
         })
         initialized = _read_response(output, 1, timeout)
         if not initialized or initialized.get("error"):
-            return None
+            return {
+                "ok": False,
+                "reason": "initialize_failed",
+                "status": None,
+                "response": initialized,
+            }
 
         _write_json_line(process, {
             "jsonrpc": "2.0",
@@ -149,13 +154,28 @@ def fetch_codex_rate_limits(session, timeout=5, popen_factory=None):
         })
         response = _read_response(output, 2, timeout)
         if not response or response.get("error"):
-            return None
+            return {
+                "ok": False,
+                "reason": "rate_limits_read_failed",
+                "status": None,
+                "response": response,
+            }
         result = response.get("result") or {}
         by_limit = result.get("rateLimitsByLimitId") or {}
         snapshot = by_limit.get("codex") or result.get("rateLimits")
-        return normalize_codex_rate_limit_snapshot(snapshot)
-    except (OSError, ValueError, BrokenPipeError):
-        return None
+        status = normalize_codex_rate_limit_snapshot(snapshot)
+        if not status:
+            return {
+                "ok": False,
+                "reason": "missing_rate_limits",
+                "status": None,
+                "response": response,
+            }
+        return {"ok": True, "reason": None, "status": status, "response": response}
+    except FileNotFoundError as error:
+        return {"ok": False, "reason": "codex_cli_not_found", "status": None, "error": str(error)}
+    except (OSError, ValueError, BrokenPipeError) as error:
+        return {"ok": False, "reason": "probe_failed", "status": None, "error": str(error)}
     finally:
         if process is not None:
             try:
@@ -166,3 +186,12 @@ def fetch_codex_rate_limits(session, timeout=5, popen_factory=None):
                     process.kill()
                 except OSError:
                     pass
+
+
+def fetch_codex_rate_limits(session, timeout=5, popen_factory=None):
+    diagnostic = fetch_codex_rate_limit_diagnostic(
+        session,
+        timeout=timeout,
+        popen_factory=popen_factory,
+    )
+    return diagnostic.get("status") if diagnostic.get("ok") else None

package/src/config.py

@@ -1,6 +1,10 @@
 import os
 from pathlib import Path
 
+PROVIDER_CODEX = "codex"
+PROVIDER_CLAUDE = "claude"
+PROVIDERS = (PROVIDER_CODEX, PROVIDER_CLAUDE)
+
 
 def get_cdx_home(env=None):
     if env is None:

package/src/notify.py

@@ -29,6 +29,13 @@ def parse_notify_args(args):
                 raise CdxError("--poll must be a number of seconds") from error
             i += 2
             continue
+        if arg.startswith("--poll="):
+            try:
+                poll = max(1, int(arg.split("=", 1)[1]))
+            except ValueError as error:
+                raise CdxError("--poll must be a number of seconds") from error
+            i += 1
+            continue
         if arg.startswith("-"):
             raise CdxError("Usage: cdx notify <name> --at-reset [--poll seconds] [--once] | cdx notify --next-ready [--poll seconds] [--once]")
         cleaned.append(arg)
@@ -121,7 +128,24 @@ def send_desktop_notification(title, message, spawn_sync=None, env=None):
         _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)
+        _run_notification_command(
+            ["osascript", "-e", script],
+            spawn_sync,
+            env,
+        )
+    elif shutil_which("notify-send", env):
+        _run_notification_command(
+            ["notify-send", str(title), str(message)],
+            spawn_sync,
+            env,
+        )
+
+
+def _run_notification_command(argv, spawn_sync, env):
+    try:
+        spawn_sync(argv, env=env, capture_output=True, text=True, timeout=5)
+    except (FileNotFoundError, OSError):
+        pass
 
 
 def _send_windows_notification(title, message, spawn_sync, env):