cdx-manager 0.3.4 → 0.4.1

package/src/backup_bundle.py

@@ -0,0 +1,134 @@
+import base64
+import hashlib
+import hmac
+import json
+import os
+from datetime import datetime, timezone
+
+from .errors import CdxError
+
+
+BUNDLE_SCHEMA_VERSION = 1
+_SALT_BYTES = 16
+_NONCE_BYTES = 16
+_SCRYPT_N = 2 ** 14
+_SCRYPT_R = 8
+_SCRYPT_P = 1
+_PBKDF2_ITERATIONS = 200000
+
+
+def _now_iso():
+    return datetime.now(timezone.utc).astimezone().isoformat()
+
+
+def _b64_encode(data):
+    return base64.b64encode(data).decode("ascii")
+
+
+def _b64_decode(data):
+    try:
+        return base64.b64decode(data.encode("ascii"))
+    except (AttributeError, ValueError, UnicodeEncodeError) as error:
+        raise CdxError("Bundle contains invalid base64 data.") from error
+
+
+def read_bundle_meta(data):
+    try:
+        wrapper = json.loads(data.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as error:
+        raise CdxError("Invalid bundle format.") from error
+
+    if wrapper.get("schema_version") != BUNDLE_SCHEMA_VERSION:
+        raise CdxError("Unsupported bundle schema version.")
+    return wrapper
+
+
+def _derive_keys(passphrase, salt):
+    if not passphrase:
+        raise CdxError("A non-empty passphrase is required for bundles that include auth data.")
+    if isinstance(passphrase, str):
+        passphrase = passphrase.encode("utf-8")
+    if hasattr(hashlib, "scrypt"):
+        key_material = hashlib.scrypt(
+            passphrase,
+            salt=salt,
+            n=_SCRYPT_N,
+            r=_SCRYPT_R,
+            p=_SCRYPT_P,
+            dklen=64,
+        )
+    else:
+        key_material = hashlib.pbkdf2_hmac(
+            "sha256",
+            passphrase,
+            salt,
+            _PBKDF2_ITERATIONS,
+            dklen=64,
+        )
+    return key_material[:32], key_material[32:]
+
+
+def _xor_keystream(data, key, nonce):
+    output = bytearray()
+    counter = 0
+    while len(output) < len(data):
+        block = hashlib.sha256(key + nonce + counter.to_bytes(8, "big")).digest()
+        output.extend(block)
+        counter += 1
+    return bytes(a ^ b for a, b in zip(data, output[:len(data)]))
+
+
+def encode_bundle(payload, include_auth=False, passphrase=None):
+    payload_bytes = json.dumps(payload, indent=2, sort_keys=True).encode("utf-8")
+    wrapper = {
+        "schema_version": BUNDLE_SCHEMA_VERSION,
+        "bundle_version": 1,
+        "created_at": _now_iso(),
+        "include_auth": bool(include_auth),
+        "encrypted": bool(include_auth),
+        "session_names": [item["name"] for item in payload.get("sessions", [])],
+    }
+    if include_auth:
+        salt = os.urandom(_SALT_BYTES)
+        nonce = os.urandom(_NONCE_BYTES)
+        enc_key, mac_key = _derive_keys(passphrase, salt)
+        ciphertext = _xor_keystream(payload_bytes, enc_key, nonce)
+        mac = hmac.new(mac_key, nonce + ciphertext, hashlib.sha256).digest()
+        wrapper.update({
+            "salt": _b64_encode(salt),
+            "nonce": _b64_encode(nonce),
+            "hmac_sha256": _b64_encode(mac),
+            "payload": _b64_encode(ciphertext),
+        })
+    else:
+        wrapper["payload"] = _b64_encode(payload_bytes)
+    return json.dumps(wrapper, indent=2).encode("utf-8")
+
+
+def decode_bundle(data, passphrase=None):
+    wrapper = read_bundle_meta(data)
+
+    encrypted = bool(wrapper.get("encrypted"))
+    payload_b64 = wrapper.get("payload")
+    if not isinstance(payload_b64, str):
+        raise CdxError("Bundle payload is missing.")
+
+    if encrypted:
+        salt = _b64_decode(wrapper.get("salt", ""))
+        nonce = _b64_decode(wrapper.get("nonce", ""))
+        expected_mac = _b64_decode(wrapper.get("hmac_sha256", ""))
+        ciphertext = _b64_decode(payload_b64)
+        enc_key, mac_key = _derive_keys(passphrase, salt)
+        actual_mac = hmac.new(mac_key, nonce + ciphertext, hashlib.sha256).digest()
+        if not hmac.compare_digest(actual_mac, expected_mac):
+            raise CdxError("Invalid bundle passphrase or corrupted bundle.")
+        payload_bytes = _xor_keystream(ciphertext, enc_key, nonce)
+    else:
+        payload_bytes = _b64_decode(payload_b64)
+
+    try:
+        payload = json.loads(payload_bytes.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as error:
+        raise CdxError("Bundle payload is corrupt.") from error
+
+    return {"meta": wrapper, "payload": payload}

package/src/cli.py

@@ -5,11 +5,14 @@ import os
 import sys
 
 from .cli_commands import (
+    API_SCHEMA_VERSION,
     STATUS_USAGE,
     handle_add,
     handle_clean,
     handle_copy,
     handle_doctor,
+    handle_export,
+    handle_import,
     handle_launch,
     handle_login,
     handle_logout,
@@ -39,8 +42,9 @@ from .status_view import (
     _format_status_detail,
     _format_status_rows,
 )
+from .update_check import check_for_update
 
-VERSION = "0.3.4"
+VERSION = "0.4.1"
 
 
 # ---------------------------------------------------------------------------
@@ -64,6 +68,8 @@ def _print_help(use_color=False):
         f"  {_style('cdx logout <name> [--json]', '36', use_color)}",
         f"  {_style('cdx rmv <name> [--force] [--json]', '36', use_color)}",
         f"  {_style('cdx clean [name] [--json]', '36', use_color)}",
+        f"  {_style('cdx export <file> [--include-auth] [--sessions a,b] [--passphrase-env VAR] [--force] [--json]', '36', use_color)}",
+        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 notify <name> --at-reset [--json]', '36', use_color)}",
@@ -96,6 +102,7 @@ def format_json_error(error):
     elif "requires an interactive terminal" in message or "requires confirmation" in message:
         code = "interactive_terminal_required"
     return json.dumps({
+        "schema_version": API_SCHEMA_VERSION,
         "ok": False,
         "error": {
             "code": code,
@@ -105,6 +112,35 @@ def format_json_error(error):
     }, indent=2)
 
 
+def _get_update_notice(service, env, options):
+    checker = options.get("checkForUpdate") or check_for_update
+    return checker(
+        service["base_dir"],
+        VERSION,
+        env=env,
+        now_fn=options.get("now"),
+    )
+
+
+def _update_warning_payload(notice):
+    if not notice:
+        return []
+    message = f"Update available: cdx-manager {notice['latest_version']} (current {VERSION})"
+    return [{
+        "code": "update_available",
+        "message": message,
+        "latest_version": notice["latest_version"],
+        "url": notice.get("url"),
+    }]
+
+
+def _update_warning_text(notice):
+    if not notice:
+        return None
+    suffix = f" {notice['url']}" if notice.get("url") else ""
+    return f"Update available: cdx-manager {notice['latest_version']} (current {VERSION}).{suffix}"
+
+
 # ---------------------------------------------------------------------------
 # main()
 # ---------------------------------------------------------------------------
@@ -145,11 +181,15 @@ def main(argv, options=None):
 
     if argv == ["--json"]:
         rows = service["format_list_rows"]()
-        out(f"{json.dumps(_list_json_payload(rows), indent=2)}\n")
+        notice = _get_update_notice(service, env, options)
+        out(f"{json.dumps(_list_json_payload(rows, notice=notice), indent=2)}\n")
         return 0
 
     if not argv:
+        notice = _get_update_notice(service, env, options)
         out(f"{_format_sessions(service, use_color=use_color)}\n")
+        if notice:
+            out(f"{_style(_update_warning_text(notice), '33', use_color)}\n")
         return 0
 
     command, *rest = argv
@@ -165,6 +205,9 @@ def main(argv, options=None):
         "spawn": spawn,
         "spawn_sync": spawn_sync,
         "stdin_is_tty": stdin_is_tty,
+        "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"
+        ) else None,
         "use_color": use_color,
     }
 
@@ -183,6 +226,12 @@ def main(argv, options=None):
     if command == "clean":
         return handle_clean(rest, ctx)
 
+    if command == "export":
+        return handle_export(rest, ctx)
+
+    if command == "import":
+        return handle_import(rest, ctx)
+
     if command == "doctor":
         return handle_doctor(rest, ctx)
 
@@ -215,12 +264,13 @@ def main(argv, options=None):
     raise CdxError(f"Unknown command: {command}. Use cdx --help.")
 
 
-def _list_json_payload(rows):
+def _list_json_payload(rows, notice=None):
     return {
+        "schema_version": API_SCHEMA_VERSION,
         "ok": True,
         "action": "list",
         "message": "Listed known sessions",
-        "warnings": [],
+        "warnings": _update_warning_payload(notice),
         "sessions": rows,
     }
 

package/src/cli_commands.py

@@ -1,4 +1,5 @@
 import asyncio
+import getpass
 import json
 import os
 from datetime import datetime
@@ -6,10 +7,9 @@ from datetime import datetime
 from .claude_refresh import _refresh_claude_sessions
 from .cli_render import _dim, _info, _success, _warn
 from .errors import CdxError
-from .health import collect_health_report, format_health_report, health_json
+from .health import collect_health_report, format_health_report
 from .notify import (
     format_notify_event,
-    notify_json,
     parse_notify_args,
     send_desktop_notification,
     wait_for_notification_event,
@@ -19,25 +19,30 @@ from .provider_runtime import (
     _list_launch_transcript_paths,
     _run_interactive_provider_command,
 )
-from .repair import format_repair_report, repair_health, repair_json
+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
 
 
 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]"
+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
 
 
 def _local_now_iso():
     return datetime.now().astimezone().isoformat()
 
 
-def _json_success(action, message, **extra):
+def _json_success(action, message, warnings=None, **extra):
     payload = {
+        "schema_version": API_SCHEMA_VERSION,
         "ok": True,
         "action": action,
         "message": message,
-        "warnings": [],
+        "warnings": warnings or [],
     }
     payload.update(extra)
     return payload
@@ -82,6 +87,142 @@ def _parse_remove_args(args):
     return {"name": names[0], "force": force}
 
 
+def _read_option_value(args, index, usage):
+    if index + 1 >= len(args):
+        raise CdxError(usage)
+    return args[index + 1], index + 2
+
+
+def _parse_session_names(value):
+    if value is None:
+        return None
+    names = [item.strip() for item in value.split(",") if item.strip()]
+    if not names:
+        raise CdxError("At least one session name is required in --sessions.")
+    return names
+
+
+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
+
+    if not parsed["file_path"]:
+        raise CdxError(EXPORT_USAGE)
+    if parsed["passphrase_env"] and not parsed["include_auth"]:
+        raise CdxError("--passphrase-env requires --include-auth for export.")
+    return parsed
+
+
+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
+
+    if not parsed["file_path"]:
+        raise CdxError(IMPORT_USAGE)
+    return parsed
+
+
+def _resolve_bundle_passphrase(ctx, env_var, prompt, confirm=False):
+    env = ctx.get("env", {})
+    if env_var:
+        passphrase = env.get(env_var)
+        if not passphrase:
+            raise CdxError(f"Environment variable {env_var} is empty or unset.")
+        return passphrase
+    if not ctx["stdin_is_tty"]:
+        raise CdxError("Encrypted bundle export/import requires an interactive terminal or --passphrase-env.")
+    getpass_fn = ctx["options"].get("getpass") or getpass.getpass
+    passphrase = getpass_fn(prompt)
+    if not passphrase:
+        raise CdxError("Bundle passphrase cannot be empty.")
+    if confirm:
+        confirmation = getpass_fn("Confirm bundle passphrase: ")
+        if passphrase != confirmation:
+            raise CdxError("Bundle passphrase confirmation does not match.")
+    return passphrase
+
+
 def _confirm_removal(name):
     answer = input(f"Remove session {name}? [y/N] ")
     return answer.strip().lower() in ("y", "yes")
@@ -269,7 +410,7 @@ def handle_doctor(rest, ctx):
         env=ctx.get("env"),
     )
     if json_flag:
-        ctx["out"](f"{health_json(report)}\n")
+        _write_json(ctx, _json_success("doctor", "Collected health report", report=report))
     else:
         ctx["out"](f"{format_health_report(report, use_color=ctx['use_color'])}\n")
     return 0
@@ -291,7 +432,7 @@ def handle_repair(rest, ctx):
         force=force,
     )
     if json_flag:
-        ctx["out"](f"{repair_json(report)}\n")
+        _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")
         if dry_run:
@@ -318,7 +459,7 @@ def handle_notify(rest, ctx):
         now_fn=ctx["options"].get("now"),
     )
     if parsed["json"]:
-        ctx["out"](f"{notify_json(event)}\n")
+        _write_json(ctx, _json_success("notify", "Resolved notification event", event=event))
     else:
         ctx["out"](f"{format_notify_event(event)}\n")
     return 0
@@ -349,12 +490,19 @@ def handle_status(rest, ctx):
         }
         for item in refresh_result.get("errors", [])
     ]
+    warnings = [
+        {
+            "code": "claude_refresh_failed",
+            "session": item.get("session") or "unknown",
+            "message": item.get("error") or "unknown error",
+        }
+        for item in refresh_errors
+    ]
 
     rows = ctx["service"]["get_status_rows"]()
     if len(args) == 0:
         if json_flag:
-            ctx["out"](f"{json.dumps(rows, indent=2)}\n")
-            _write_refresh_warnings(refresh_errors, ctx, stream="err")
+            _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")
         _write_refresh_warnings(refresh_errors, ctx)
@@ -364,8 +512,7 @@ def handle_status(rest, ctx):
     if not row:
         raise CdxError(f"Unknown session: {args[0]}")
     if json_flag:
-        ctx["out"](f"{json.dumps(row, indent=2)}\n")
-        _write_refresh_warnings(refresh_errors, ctx, stream="err")
+        _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")
     _write_refresh_warnings(refresh_errors, ctx)
@@ -380,6 +527,74 @@ def _write_refresh_warnings(refresh_errors, ctx, stream="out"):
         write(f"{_warn(f'Warning: Claude refresh failed for {session}: {error}', ctx['use_color'])}\n")
 
 
+def handle_export(rest, ctx):
+    parsed = _parse_export_args(rest)
+    passphrase = None
+    if parsed["include_auth"]:
+        passphrase = _resolve_bundle_passphrase(
+            ctx,
+            parsed["passphrase_env"],
+            "Bundle passphrase: ",
+            confirm=True,
+        )
+    result = ctx["service"]["export_bundle"](
+        parsed["file_path"],
+        include_auth=parsed["include_auth"],
+        session_names=parsed["session_names"],
+        passphrase=passphrase,
+        force=parsed["force"],
+    )
+    session_count = len(result["session_names"])
+    auth_suffix = " with auth" if result["include_auth"] else ""
+    message = f"Exported {session_count} session{'s' if session_count != 1 else ''}{auth_suffix} to {result['path']}"
+    payload = _json_success(
+        "export",
+        message,
+        bundle=result,
+    )
+    if parsed["json"]:
+        _write_json(ctx, payload)
+        return 0
+    ctx["out"](f"{_success(message, ctx['use_color'])}\n")
+    return 0
+
+
+def handle_import(rest, ctx):
+    parsed = _parse_import_args(rest)
+    passphrase = None
+    try:
+        with open(parsed["file_path"], "rb") as handle:
+            meta = read_bundle_meta(handle.read())
+    except OSError as error:
+        raise CdxError(f"Bundle file not found: {parsed['file_path']}") from error
+    if meta.get("encrypted"):
+        passphrase = _resolve_bundle_passphrase(
+            ctx,
+            parsed["passphrase_env"],
+            "Bundle passphrase: ",
+            confirm=False,
+        )
+    result = ctx["service"]["import_bundle"](
+        parsed["file_path"],
+        passphrase=passphrase,
+        session_names=parsed["session_names"],
+        force=parsed["force"],
+    )
+    session_count = len(result["session_names"])
+    auth_suffix = " with auth" if result["include_auth"] else ""
+    message = f"Imported {session_count} session{'s' if session_count != 1 else ''}{auth_suffix} from {result['path']}"
+    payload = _json_success(
+        "import",
+        message,
+        bundle=result,
+    )
+    if parsed["json"]:
+        _write_json(ctx, payload)
+        return 0
+    ctx["out"](f"{_success(message, ctx['use_color'])}\n")
+    return 0
+
+
 def handle_login(rest, ctx):
     json_flag, args = _parse_json_flag(rest)
     if len(args) != 1:
@@ -436,6 +651,15 @@ def handle_logout(rest, ctx):
 
 def handle_launch(command, ctx):
     json_flag = "--json" in ctx["options"].get("raw_args", [])
+    update_notice = ctx.get("update_notice")
+    warnings = []
+    if update_notice:
+        warnings.append({
+            "code": "update_available",
+            "message": f"Update available: cdx-manager {update_notice['latest_version']}",
+            "latest_version": update_notice["latest_version"],
+            "url": update_notice.get("url"),
+        })
     session = ctx["service"]["launch_session"](command)
     _ensure_session_authentication(
         session,
@@ -450,6 +674,11 @@ def handle_launch(command, ctx):
     message = f"Launching {session['provider']} session {session['name']}"
     if not json_flag:
         ctx["out"](f"{_info(message, ctx['use_color'])}\n")
+        if update_notice:
+            text = f"Update available: cdx-manager {update_notice['latest_version']} (current version installed may be older)."
+            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: run /status once the Codex session opens.', ctx['use_color'])}\n")
@@ -458,5 +687,5 @@ def handle_launch(command, ctx):
         signal_emitter=ctx.get("signal_emitter")
     )
     if json_flag:
-        _write_json(ctx, _json_success("launch", message, session=ctx["service"]["get_session"](session["name"])))
+        _write_json(ctx, _json_success("launch", message, warnings=warnings, session=ctx["service"]["get_session"](session["name"])))
     return 0