gluekit 1.0.1.dev1__py3-none-any.whl

gluekit/commands/helpers.py

@@ -0,0 +1,1068 @@
+from __future__ import annotations
+
+import csv
+import json
+import re
+import subprocess
+from collections.abc import Mapping
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Optional
+
+import typer
+from slugify import slugify
+
+from ..job_mgmt.glue_jobs import (
+    normalize_glue_config_data,
+    _resolve_notebook_path,
+)
+
+from .constants import GLUE_SET_FILE
+
+
+def _examples_epilog(*lines: str) -> str:
+    examples = "\n\n".join(f"- `{line.strip()}`" for line in lines)
+    return f"\n\n**Examples**\n\n{examples}"
+
+
+def _find_workspace_root(start: Optional[Path] = None) -> Path:
+    current = (start or Path.cwd()).resolve()
+    for candidate in [current, *current.parents]:
+        if (candidate / "pyproject.toml").exists():
+            return candidate
+    return current
+
+
+def run_command(
+    command: list[str],
+    cwd: Optional[Path] = None,
+    dry_run: bool = False,
+    verbose: bool = False,
+) -> None:
+    display = " ".join(command)
+    if dry_run or verbose:
+        typer.echo(f"{'Would run' if dry_run else 'Running'}: {display}")
+    if dry_run:
+        return
+    try:
+        subprocess.run(
+            command,
+            cwd=str(cwd) if cwd else None,
+            check=True,
+            text=True,
+        )
+    except FileNotFoundError as exc:
+        raise typer.BadParameter(f"Command not found: {command[0]}") from exc
+    except subprocess.CalledProcessError as exc:
+        raise typer.Exit(code=exc.returncode) from exc
+
+
+def _emit_compatibility_notice(command_name: str, replacement_hint: str) -> None:
+    typer.echo(
+        f"Note: 'gluekit {command_name}' is kept for compatibility. Prefer 'gluekit edit' {replacement_hint}."
+    )
+
+
+def _raise_missing_local_config(
+    job_name: str, config_dir: Path, command_label: str
+) -> None:
+    checked_out_jobs = _get_checked_out_jobs()
+    if job_name in checked_out_jobs:
+        raise typer.BadParameter(
+            f'No local config files matched "{job_name}" in {config_dir}. '
+            f"This checked-out job is selected for local work, but it does not have a local config yet. "
+            f"Create or clone a config before running {command_label}."
+        )
+    raise typer.BadParameter(f'No config files matched "{job_name}" in {config_dir}.')
+
+
+def _looks_like_remote_module_spec(item: str) -> bool:
+    normalized = item.strip()
+    if not normalized:
+        return False
+    return bool(re.match(r"^[a-zA-Z][a-zA-Z0-9+.-]*://", normalized))
+
+
+def _routes_to_additional_python_modules(path: Path) -> bool:
+    return path.suffix.lower() == ".whl"
+
+
+def _collect_config_local_artifact_paths(
+    config_data: dict[str, Any],
+    *,
+    job_name: str,
+    include_additional_python_files: bool,
+    include_extra_files: bool,
+) -> list[tuple[str, Path]]:
+    sc = config_data.get("SourceControlDetails", {}) or {}
+    if not isinstance(sc, dict):
+        sc = {}
+
+    script_path = Path(
+        sc.get("ScriptLocation")
+        or sc.get("LocalPath")
+        or f"glue/scripts/{slugify(job_name)}.py"
+    )
+    notebook_value = sc.get("NotebookLocation") or sc.get("NotebookPath")
+    notebook_path = (
+        Path(notebook_value)
+        if isinstance(notebook_value, str)
+        else Path(_resolve_notebook_path(script_path))
+    )
+
+    artifacts: list[tuple[str, Path]] = [
+        ("script", script_path),
+        ("notebook", notebook_path),
+    ]
+
+    def append_entries(label: str, value: Any, kind: str) -> None:
+        entries = value
+        if entries is None:
+            return
+        if isinstance(entries, dict):
+            entries = [entries]
+        if not isinstance(entries, list):
+            return
+        for entry in entries:
+            if not isinstance(entry, dict):
+                continue
+            local_path = (
+                entry.get("LocalPath")
+                or entry.get("local_path")
+                or entry.get("localPath")
+            )
+            if isinstance(local_path, str) and local_path.strip():
+                artifacts.append((kind, Path(local_path)))
+
+    if include_additional_python_files:
+        append_entries(
+            "AdditionalPythonFiles",
+            sc.get("AdditionalPythonFiles"),
+            "additional-python-file",
+        )
+        append_entries("ExtraPyFiles", sc.get("ExtraPyFiles"), "extra-py-file")
+    if include_extra_files:
+        append_entries("AdditionalFiles", sc.get("AdditionalFiles"), "extra-file")
+        append_entries("ExtraFiles", sc.get("ExtraFiles"), "extra-file")
+
+    return artifacts
+
+
+def _set_saved_scope(
+    parsed: dict[str, Any],
+    job_name: Optional[str],
+    global_scope: bool,
+    profile: Optional[str] = None,
+) -> str:
+    if global_scope and job_name:
+        raise typer.BadParameter("Use either <job-name> or --global, not both.")
+    store = _load_glue_set_store()
+
+    profile_name = profile.strip() if isinstance(profile, str) else None
+    if profile_name:
+        profiles = store.setdefault("profiles", {})
+        profile_store = profiles.setdefault(profile_name, {})
+        if not isinstance(profile_store, dict):
+            profile_store = {}
+            profiles[profile_name] = profile_store
+        if not isinstance(profile_store.get("global"), dict):
+            profile_store["global"] = {}
+        if not isinstance(profile_store.get("jobs"), dict):
+            profile_store["jobs"] = {}
+        base = profile_store
+    else:
+        base = store
+
+    if global_scope:
+        target = f"profile:{profile_name}:global" if profile_name else "global"
+        scope = base.setdefault("global", {})
+    else:
+        if not job_name:
+            raise typer.BadParameter("Provide <job-name> or use --global.")
+        target = f"profile:{profile_name}:{job_name}" if profile_name else job_name
+        jobs = base.setdefault("jobs", {})
+        scope = jobs.setdefault(job_name, {})
+
+    if not isinstance(scope, dict):
+        scope = {}
+        if global_scope:
+            base["global"] = scope
+        else:
+            base.setdefault("jobs", {})[job_name] = scope
+
+    scope.update(parsed)
+    _save_glue_set_store(store)
+    return target
+
+
+def _load_config_index(config_dir: Path) -> dict[str, dict[str, Any]]:
+    config_index: dict[str, dict[str, Any]] = {}
+    for config_path in config_dir.glob("*.json"):
+        try:
+            config_data = normalize_glue_config_data(
+                json.loads(config_path.read_text())
+            )
+        except json.JSONDecodeError:
+            continue
+        job_name = config_data.get("Name")
+        if job_name:
+            config_index[job_name] = {
+                "config_path": config_path,
+                "config": config_data,
+            }
+    return config_index
+
+
+def _parse_s3_url(s3_url: str) -> tuple[str, str]:
+    if not s3_url.startswith("s3://"):
+        raise typer.BadParameter(f"Invalid S3 URL: {s3_url}")
+    bucket_key = s3_url[5:]
+    if "/" not in bucket_key:
+        raise typer.BadParameter(f"Invalid S3 URL (missing key): {s3_url}")
+    bucket, key = bucket_key.split("/", 1)
+    return bucket, key
+
+
+def _find_sequence(parts: tuple[str, ...], sequence: tuple[str, ...]) -> Optional[int]:
+    if not sequence:
+        return None
+    for idx in range(len(parts) - len(sequence) + 1):
+        if parts[idx : idx + len(sequence)] == sequence:
+            return idx
+    return None
+
+
+def _derive_s3_target(
+    local_path: Path,
+    job_name: str,
+    script_location: str,
+    local_script_path: Path,
+) -> str:
+    bucket, script_key = _parse_s3_url(script_location)
+    script_dir_parts = Path(script_key).parent.parts
+    local_script_dir_parts = local_script_path.parent.parts
+    local_root = None
+
+    if script_dir_parts:
+        idx = _find_sequence(local_script_dir_parts, script_dir_parts)
+        if idx is not None:
+            local_root = Path(*local_script_dir_parts[: idx + len(script_dir_parts)])
+
+    if local_root and local_path.is_relative_to(local_root):
+        rel = local_path.relative_to(local_root)
+        s3_key = Path(*script_dir_parts) / rel
+        return f"s3://{bucket}/{s3_key.as_posix()}"
+
+    if local_path.parts and local_path.parts[0] == "glue":
+        rel = (
+            Path(*local_path.parts[1:])
+            if len(local_path.parts) > 1
+            else Path(local_path.name)
+        )
+        return f"s3://{bucket}/{rel.as_posix()}"
+
+    job_candidates = {job_name, slugify(job_name)}
+    for candidate in job_candidates:
+        if candidate in local_path.parts:
+            idx = local_path.parts.index(candidate)
+            s3_key = Path(*local_path.parts[idx:])
+            return f"s3://{bucket}/{s3_key.as_posix()}"
+
+    if not local_path.is_absolute() and len(local_path.parts) > 1:
+        return f"s3://{bucket}/{local_path.as_posix()}"
+
+    return f"s3://{bucket}/{local_path.name}"
+
+
+def _load_glue_set_store() -> dict[str, Any]:
+    if not GLUE_SET_FILE.exists():
+        return {
+            "global": {},
+            "jobs": {},
+            "profiles": {},
+            "checkout": {},
+        }
+    try:
+        data = json.loads(GLUE_SET_FILE.read_text())
+    except json.JSONDecodeError:
+        return {
+            "global": {},
+            "jobs": {},
+            "profiles": {},
+            "checkout": {},
+        }
+    if not isinstance(data, dict):
+        return {
+            "global": {},
+            "jobs": {},
+            "profiles": {},
+            "checkout": {},
+        }
+    if not isinstance(data.get("global"), dict):
+        data["global"] = {}
+    if not isinstance(data.get("jobs"), dict):
+        data["jobs"] = {}
+    if not isinstance(data.get("profiles"), dict):
+        data["profiles"] = {}
+    for profile_name, profile_data in list(data["profiles"].items()):
+        if not isinstance(profile_name, str) or not isinstance(profile_data, dict):
+            data["profiles"].pop(profile_name, None)
+            continue
+        if not isinstance(profile_data.get("global"), dict):
+            profile_data["global"] = {}
+        if not isinstance(profile_data.get("jobs"), dict):
+            profile_data["jobs"] = {}
+    if not isinstance(data.get("checkout"), dict):
+        data["checkout"] = {}
+    data.pop("local_checkouts", None)
+    _normalize_checkout_local(data["checkout"])
+    return data
+
+
+def _normalize_checkout_local(checkout: dict[str, Any]) -> None:
+    local_value = checkout.get("local")
+    if isinstance(local_value, dict):
+        local_data = {
+            key: value.strip()
+            for key, value in local_value.items()
+            if isinstance(key, str) and isinstance(value, str) and value.strip()
+        }
+        if isinstance(local_data.get("name"), str):
+            checkout["local"] = local_data
+            return
+
+    checkout.pop("local", None)
+
+
+def _save_glue_set_store(data: dict[str, Any]) -> None:
+    GLUE_SET_FILE.parent.mkdir(parents=True, exist_ok=True)
+    GLUE_SET_FILE.write_text(json.dumps(data, indent=4))
+
+
+def _resolve_single_job_name(job_name: Optional[str], context_label: str) -> str:
+    if job_name:
+        return job_name
+
+    checked_out_jobs = _get_checked_out_jobs()
+    if not checked_out_jobs:
+        raise typer.BadParameter(
+            f"Provide <job-name> or run 'gluekit checkout <job-name>' before {context_label}."
+        )
+    if len(checked_out_jobs) != 1:
+        raise typer.BadParameter(
+            f"{context_label} requires a single active checkout selection; found {len(checked_out_jobs)} jobs in {GLUE_SET_FILE}."
+        )
+    return checked_out_jobs[0]
+
+
+def _get_saved_params_for_job(
+    job_name: str, profile: Optional[str] = None
+) -> dict[str, Any]:
+    store = _load_glue_set_store()
+    global_params = store.get("global", {})
+    job_params = store.get("jobs", {}).get(job_name, {})
+    profile_name = profile.strip() if isinstance(profile, str) else None
+    profile_store = store.get("profiles", {}).get(profile_name, {})
+    profile_global_params = {}
+    profile_job_params = {}
+    if isinstance(profile_store, dict):
+        profile_global_params = profile_store.get("global", {})
+        profile_job_params = profile_store.get("jobs", {}).get(job_name, {})
+
+    merged: dict[str, Any] = {}
+    if isinstance(global_params, dict):
+        merged.update(global_params)
+    if isinstance(job_params, dict):
+        merged.update(job_params)
+    if isinstance(profile_global_params, dict):
+        merged.update(profile_global_params)
+    if isinstance(profile_job_params, dict):
+        merged.update(profile_job_params)
+    return merged
+
+
+def _get_checked_out_profile() -> Optional[str]:
+    store = _load_glue_set_store()
+    checkout = store.get("checkout", {})
+    if not isinstance(checkout, dict):
+        return None
+    profile = checkout.get("profile")
+    if isinstance(profile, str) and profile.strip():
+        return profile.strip()
+    return None
+
+
+def _get_local_checkouts() -> dict[str, dict[str, Any]]:
+    local_setup = _get_checked_out_local_setup()
+    if not local_setup:
+        return {}
+    name = local_setup.get("name")
+    if not isinstance(name, str) or not name.strip():
+        return {}
+    return {name: local_setup}
+
+
+def _save_local_checkout(name: str, data: dict[str, Any]) -> None:
+    normalized_name = name.strip()
+    if not normalized_name:
+        raise typer.BadParameter("Local setup name must be a non-empty string.")
+    store = _load_glue_set_store()
+    checkout = store.setdefault("checkout", {})
+    if not isinstance(checkout, dict):
+        checkout = {}
+        store["checkout"] = checkout
+    checkout["local"] = {
+        "name": normalized_name,
+        **{
+            key: value.strip()
+            for key, value in data.items()
+            if isinstance(key, str) and isinstance(value, str) and value.strip()
+        },
+    }
+    _save_glue_set_store(store)
+
+
+def _get_checked_out_local_setup_name() -> Optional[str]:
+    store = _load_glue_set_store()
+    checkout = store.get("checkout", {})
+    if not isinstance(checkout, dict):
+        return None
+    local_name = checkout.get("local")
+    if isinstance(local_name, dict):
+        name = local_name.get("name")
+        if isinstance(name, str) and name.strip():
+            return name.strip()
+    return None
+
+
+def _get_checked_out_local_setup() -> Optional[dict[str, Any]]:
+    store = _load_glue_set_store()
+    checkout = store.get("checkout", {})
+    if not isinstance(checkout, dict):
+        return None
+    local_setup = checkout.get("local")
+    if not isinstance(local_setup, dict):
+        return None
+    name = local_setup.get("name")
+    if not isinstance(name, str) or not name.strip():
+        return None
+    return dict(local_setup)
+
+
+def _set_checked_out_local_setup(name: str) -> None:
+    normalized_name = name.strip()
+    if not normalized_name:
+        raise typer.BadParameter("Local setup name must be a non-empty string.")
+    store = _load_glue_set_store()
+    checkout = store.setdefault("checkout", {})
+    if not isinstance(checkout, dict):
+        checkout = {}
+        store["checkout"] = checkout
+    existing_local = checkout.get("local")
+    next_local: dict[str, str] = {"name": normalized_name}
+    if isinstance(existing_local, dict):
+        for key in ("profile", "job", "mode"):
+            value = existing_local.get(key)
+            if isinstance(value, str) and value.strip():
+                next_local[key] = value.strip()
+    checkout["local"] = next_local
+    _save_glue_set_store(store)
+
+
+def _parse_config_field_path(field_path: str) -> list[str | int]:
+    parts: list[str | int] = []
+    for raw_part in field_path.split("."):
+        if not raw_part:
+            return []
+        name, bracket, remainder = raw_part.partition("[")
+        if name:
+            parts.append(name)
+        while bracket:
+            index_text, closing, remainder = remainder.partition("]")
+            if closing != "]" or not index_text.isdigit():
+                return []
+            parts.append(int(index_text))
+            bracket = ""
+            if remainder:
+                if not remainder.startswith("["):
+                    return []
+                bracket = "["
+                remainder = remainder[1:]
+    return parts
+
+
+def _set_config_field_path(
+    config_data: dict[str, Any],
+    field_path: str,
+    value: Any,
+    changes: list[str],
+) -> bool:
+    parts = _parse_config_field_path(field_path)
+    if not parts:
+        return False
+
+    current: Any = config_data
+    for index, part in enumerate(parts[:-1]):
+        next_part = parts[index + 1]
+        if isinstance(part, int):
+            if not isinstance(current, list) or part >= len(current):
+                return False
+            current = current[part]
+            continue
+
+        if not isinstance(current, dict):
+            return False
+        if part not in current:
+            if isinstance(next_part, int):
+                return False
+            current[part] = {}
+        current = current[part]
+
+    final_part = parts[-1]
+    if isinstance(final_part, int):
+        if not isinstance(current, list) or final_part >= len(current):
+            return False
+        if current[final_part] != value:
+            current[final_part] = value
+            changes.append(field_path)
+        return True
+
+    if not isinstance(current, dict):
+        return False
+    _set_if_changed(current, final_part, value, changes)
+    return True
+
+
+def _saved_param_config_value(value: Any) -> Any:
+    if (
+        isinstance(value, dict)
+        and isinstance(value.get("remote"), str)
+        and "local" in value
+    ):
+        return value["remote"]
+    return _to_csv_if_list(value)
+
+
+def _get_config_field_path(config_data: dict[str, Any], field_path: str) -> Any:
+    parts = _parse_config_field_path(field_path)
+    if not parts:
+        return None
+
+    current: Any = config_data
+    for part in parts:
+        if isinstance(part, int):
+            if not isinstance(current, list) or part >= len(current):
+                return None
+            current = current[part]
+            continue
+        if not isinstance(current, dict) or part not in current:
+            return None
+        current = current[part]
+    return current
+
+
+def _profile_param_expected_fields(key: str, value: Any) -> list[tuple[str, Any]]:
+    normalized_key = key.strip()
+    if normalized_key.startswith(
+        (
+            "Command.",
+            "DefaultArguments.",
+            "NonOverridableArguments.",
+            "SourceControlDetails.",
+        )
+    ):
+        expected = (
+            _saved_param_config_value(value)
+            if normalized_key.startswith(
+                ("DefaultArguments.", "NonOverridableArguments.")
+            )
+            else value
+        )
+        return [(normalized_key, expected)]
+    if normalized_key in {"script_location", "local_script_path", "local_path"}:
+        return [("SourceControlDetails.ScriptLocation", str(value))]
+    if normalized_key in {"notebook_location", "notebook_path"}:
+        expected = str(value)
+        return [
+            ("SourceControlDetails.NotebookLocation", expected),
+            ("SourceControlDetails.NotebookPath", expected),
+        ]
+    if normalized_key in {"command_script_location", "remote_script_location"}:
+        return [("Command.ScriptLocation", str(value))]
+    if normalized_key == "extra_py_files":
+        return [("DefaultArguments.--extra-py-files", _to_csv_if_list(value))]
+    if normalized_key == "extra_files":
+        return [("DefaultArguments.--extra-files", _to_csv_if_list(value))]
+    if normalized_key == "additional_python_modules":
+        return [
+            (
+                "DefaultArguments.--additional-python-modules",
+                _saved_param_config_value(value),
+            )
+        ]
+    if normalized_key == "default_arguments" and isinstance(value, dict):
+        fields: list[tuple[str, Any]] = []
+        for arg_key, arg_value in value.items():
+            final_key = arg_key if arg_key.startswith("--") else f"--{arg_key}"
+            fields.append(
+                (
+                    f"DefaultArguments.{final_key}",
+                    _saved_param_config_value(arg_value),
+                )
+            )
+        return fields
+    if normalized_key.startswith("default_arguments."):
+        arg_key = normalized_key.split(".", 1)[1]
+        final_key = arg_key if arg_key.startswith("--") else f"--{arg_key}"
+        return [
+            (
+                f"DefaultArguments.{final_key}",
+                _saved_param_config_value(value),
+            )
+        ]
+    if normalized_key.startswith("source_control."):
+        sc_key = normalized_key.split(".", 1)[1]
+        return [(f"SourceControlDetails.{sc_key}", value)]
+    if normalized_key.startswith("command."):
+        cmd_key = normalized_key.split(".", 1)[1]
+        return [(f"Command.{cmd_key}", value)]
+    if normalized_key.startswith("--"):
+        return [(f"DefaultArguments.{normalized_key}", _to_csv_if_list(value))]
+    return [(normalized_key, value)]
+
+
+def _collect_profile_mapping_mismatches(
+    config_data: dict[str, Any],
+    params: dict[str, Any],
+) -> list[str]:
+    mismatches: list[str] = []
+    for key, value in params.items():
+        for field_path, expected in _profile_param_expected_fields(key, value):
+            actual = _get_config_field_path(config_data, field_path)
+            if actual != expected:
+                mismatches.append(
+                    f"{field_path}: expected {expected!r}, found {actual!r}"
+                )
+    return mismatches
+
+
+def _validate_profile_mappings_align_with_config(
+    *,
+    job_name: str,
+    config_data: dict[str, Any],
+    profile: Optional[str],
+    success_message: Optional[str] = None,
+) -> None:
+    saved_params = _get_saved_params_for_job(job_name, profile=profile)
+    if not saved_params:
+        return
+
+    mismatches = _collect_profile_mapping_mismatches(config_data, saved_params)
+    profile_label = f" for profile {profile}" if profile else ""
+    if mismatches:
+        rendered = "\n".join(f"- {mismatch}" for mismatch in mismatches)
+        raise typer.BadParameter(
+            f"Profile mappings do not align with config{profile_label}: {job_name}\n"
+            f"{rendered}"
+        )
+
+    if success_message:
+        typer.echo(success_message)
+
+
+def _apply_saved_params_to_config(
+    config_data: dict[str, Any], params: dict[str, Any]
+) -> list[str]:
+    changes: list[str] = []
+    default_args = config_data.setdefault("DefaultArguments", {})
+    source_control = config_data.setdefault("SourceControlDetails", {})
+    command = config_data.setdefault("Command", {})
+
+    for key, value in params.items():
+        normalized_key = key.strip()
+        if normalized_key.startswith(
+            (
+                "Command.",
+                "DefaultArguments.",
+                "NonOverridableArguments.",
+                "SourceControlDetails.",
+            )
+        ):
+            config_value = (
+                _saved_param_config_value(value)
+                if normalized_key.startswith(
+                    ("DefaultArguments.", "NonOverridableArguments.")
+                )
+                else value
+            )
+            if not _set_config_field_path(
+                config_data, normalized_key, config_value, changes
+            ):
+                changes.append(f"Skipped unresolved saved param path: {normalized_key}")
+        elif normalized_key in {"script_location", "local_script_path", "local_path"}:
+            _set_if_changed(source_control, "ScriptLocation", str(value), changes)
+        elif normalized_key in {"notebook_location", "notebook_path"}:
+            _set_if_changed(source_control, "NotebookLocation", str(value), changes)
+            _set_if_changed(source_control, "NotebookPath", str(value), changes)
+        elif normalized_key in {"command_script_location", "remote_script_location"}:
+            _set_if_changed(command, "ScriptLocation", str(value), changes)
+        elif normalized_key == "extra_py_files":
+            _set_if_changed(
+                default_args, "--extra-py-files", _to_csv_if_list(value), changes
+            )
+        elif normalized_key == "extra_files":
+            _set_if_changed(
+                default_args, "--extra-files", _to_csv_if_list(value), changes
+            )
+        elif normalized_key == "additional_python_modules":
+            _set_if_changed(
+                default_args,
+                "--additional-python-modules",
+                _saved_param_config_value(value),
+                changes,
+            )
+        elif normalized_key == "default_arguments" and isinstance(value, dict):
+            for arg_key, arg_value in value.items():
+                final_key = arg_key if arg_key.startswith("--") else f"--{arg_key}"
+                _set_if_changed(
+                    default_args,
+                    final_key,
+                    _saved_param_config_value(arg_value),
+                    changes,
+                )
+        elif normalized_key.startswith("default_arguments."):
+            arg_key = normalized_key.split(".", 1)[1]
+            final_key = arg_key if arg_key.startswith("--") else f"--{arg_key}"
+            _set_if_changed(
+                default_args, final_key, _saved_param_config_value(value), changes
+            )
+        elif normalized_key.startswith("source_control."):
+            sc_key = normalized_key.split(".", 1)[1]
+            _set_if_changed(source_control, sc_key, value, changes)
+        elif normalized_key.startswith("command."):
+            cmd_key = normalized_key.split(".", 1)[1]
+            _set_if_changed(command, cmd_key, value, changes)
+        elif normalized_key.startswith("--"):
+            _set_if_changed(
+                default_args, normalized_key, _to_csv_if_list(value), changes
+            )
+        else:
+            _set_if_changed(config_data, normalized_key, value, changes)
+
+    return changes
+
+
+def _get_checked_out_jobs() -> list[str]:
+    store = _load_glue_set_store()
+    checkout = store.get("checkout", {})
+    if not isinstance(checkout, dict):
+        return []
+    jobs = checkout.get("jobs")
+    if not isinstance(jobs, list):
+        return []
+    normalized: list[str] = []
+    for job_name in jobs:
+        if not isinstance(job_name, str):
+            continue
+        value = job_name.strip()
+        if value and value not in normalized:
+            normalized.append(value)
+    return normalized
+
+
+def _save_checked_out_jobs(
+    job_names: list[str],
+    selector: str,
+    source: str = "local",
+    profile: Optional[str] = None,
+) -> None:
+    store = _load_glue_set_store()
+    checkout = {
+        "mode": "job",
+        "selector": selector,
+        "source": source,
+        "jobs": list(job_names),
+    }
+    existing_checkout = store.get("checkout", {})
+    if isinstance(existing_checkout, dict) and isinstance(
+        existing_checkout.get("local"), dict
+    ):
+        checkout["local"] = existing_checkout["local"]
+    profile_name = profile.strip() if isinstance(profile, str) else None
+    if profile_name:
+        checkout["profile"] = profile_name
+    store["checkout"] = checkout
+    _save_glue_set_store(store)
+
+
+def _clear_checked_out_jobs() -> None:
+    store = _load_glue_set_store()
+    store["checkout"] = {}
+    _save_glue_set_store(store)
+
+
+def _save_checkout_local_paths(
+    *,
+    job_name: str,
+    config_path: Path,
+    config_data: dict[str, Any],
+    dry_run: bool = False,
+) -> dict[str, str]:
+    sc = config_data.get("SourceControlDetails", {})
+    if not isinstance(sc, dict):
+        sc = {}
+    script_path = Path(
+        sc.get("ScriptLocation")
+        or sc.get("LocalPath")
+        or f"glue/scripts/{slugify(job_name)}.py"
+    )
+    notebook_value = sc.get("NotebookLocation") or sc.get("NotebookPath")
+    notebook_path = (
+        Path(notebook_value)
+        if isinstance(notebook_value, str)
+        else Path(_resolve_notebook_path(script_path))
+    )
+    paths = {
+        "config": config_path.as_posix(),
+        "script": script_path.as_posix(),
+        "notebook": notebook_path.as_posix(),
+    }
+    if dry_run:
+        typer.echo(f"Would save checkout local paths for {job_name}: {paths}")
+        return paths
+
+    store = _load_glue_set_store()
+    checkout = store.setdefault("checkout", {})
+    if not isinstance(checkout, dict):
+        checkout = {}
+        store["checkout"] = checkout
+    local_paths = checkout.setdefault("local_paths", {})
+    if not isinstance(local_paths, dict):
+        local_paths = {}
+        checkout["local_paths"] = local_paths
+    local_paths[job_name] = paths
+    _save_glue_set_store(store)
+    return paths
+
+
+def _apply_saved_params_to_config_path(
+    *,
+    config_path: Path,
+    config_data: dict[str, Any],
+    job_name: str,
+    profile: Optional[str],
+    dry_run: bool,
+) -> list[str]:
+    saved_params = _get_saved_params_for_job(job_name, profile=profile)
+    if not saved_params:
+        return []
+    changes = _apply_saved_params_to_config(config_data, saved_params)
+    if not changes:
+        return []
+    profile_label = f" for profile {profile}" if profile else ""
+    if dry_run:
+        typer.echo(f"Would apply saved params{profile_label}: {job_name}")
+    else:
+        config_path.write_text(json.dumps(config_data, indent=4))
+        typer.echo(f"Applied saved params{profile_label}: {job_name}")
+    return changes
+
+
+def _resolve_checkout_job_name(
+    job_name: str,
+    *,
+    config_dir: Path,
+) -> tuple[str, str]:
+    normalized_job_name = job_name.strip()
+    if not normalized_job_name:
+        raise typer.BadParameter("Job name must be a non-empty string.")
+
+    config_index = _load_config_index(config_dir)
+    if normalized_job_name in config_index:
+        return normalized_job_name, "local"
+
+    return normalized_job_name, "offline"
+
+
+def _coerce_set_value(raw: str) -> Any:
+    value = raw.strip()
+    lower = value.lower()
+    if lower == "true":
+        return True
+    if lower == "false":
+        return False
+    if lower in {"null", "none"}:
+        return None
+    if (value.startswith("{") and value.endswith("}")) or (
+        value.startswith("[") and value.endswith("]")
+    ):
+        try:
+            return json.loads(value)
+        except json.JSONDecodeError:
+            return raw
+    try:
+        return int(value)
+    except ValueError:
+        pass
+    try:
+        return float(value)
+    except ValueError:
+        return raw
+
+
+def _format_csv_item(item: str) -> str:
+    if any(ch in item for ch in [",", '"']):
+        escaped = item.replace('"', '""')
+        return f'"{escaped}"'
+    return item
+
+
+def _set_if_changed(
+    container: dict[str, Any], key: str, value: Any, changes: list[str]
+) -> None:
+    if container.get(key) != value:
+        container[key] = value
+        changes.append(key)
+
+
+def _write_config_changes(
+    config_path: Path,
+    config_data: dict[str, Any],
+    changes: list[str],
+    *,
+    dry_run: bool,
+) -> None:
+    if not changes:
+        typer.echo("No changes needed.")
+        return
+
+    actionable_changes = [
+        change for change in changes if not change.startswith("Skipped ")
+    ]
+    if not actionable_changes:
+        typer.echo("No changes needed.")
+        for change in changes:
+            typer.echo(f"- {change}")
+        return
+
+    if dry_run:
+        typer.echo(f"Would update {config_path}:")
+        for change in changes:
+            typer.echo(f"- {change}")
+        return
+
+    config_path.write_text(json.dumps(config_data, indent=4))
+    typer.echo(f"Updated {config_path}:")
+    for change in changes:
+        typer.echo(f"- {change}")
+
+
+def _to_csv_if_list(value: Any) -> Any:
+    if isinstance(value, list):
+        return ",".join(str(item) for item in value)
+    return value
+
+
+__all__ = [
+    "_examples_epilog",
+    "_find_workspace_root",
+    "run_command",
+    "_emit_compatibility_notice",
+    "_raise_missing_local_config",
+    "_looks_like_remote_module_spec",
+    "_routes_to_additional_python_modules",
+    "_collect_config_local_artifact_paths",
+    "_set_saved_scope",
+    "_load_config_index",
+    "_parse_s3_url",
+    "_find_sequence",
+    "_derive_s3_target",
+    "_load_glue_set_store",
+    "_save_glue_set_store",
+    "_resolve_single_job_name",
+    "_get_saved_params_for_job",
+    "_get_checked_out_profile",
+    "_get_local_checkouts",
+    "_save_local_checkout",
+    "_get_checked_out_local_setup_name",
+    "_get_checked_out_local_setup",
+    "_set_checked_out_local_setup",
+    "_get_config_field_path",
+    "_profile_param_expected_fields",
+    "_collect_profile_mapping_mismatches",
+    "_validate_profile_mappings_align_with_config",
+    "_apply_saved_params_to_config",
+    "_get_checked_out_jobs",
+    "_save_checked_out_jobs",
+    "_clear_checked_out_jobs",
+    "_save_checkout_local_paths",
+    "_apply_saved_params_to_config_path",
+    "_resolve_checkout_job_name",
+    "_coerce_set_value",
+    "_format_csv_item",
+    "_set_if_changed",
+    "_write_config_changes",
+    "_to_csv_if_list",
+    "_parse_datetime",
+    "_get_local_last_modified",
+    "_write_glue_job_list_csv",
+]
+
+
+def _parse_datetime(value: Any) -> Optional[datetime]:
+    if not value:
+        return None
+    if isinstance(value, datetime):
+        parsed = value
+    elif isinstance(value, (int, float)):
+        try:
+            parsed = datetime.fromtimestamp(value, tz=timezone.utc)
+        except (OverflowError, OSError, ValueError):
+            return None
+    elif isinstance(value, str):
+        text = value.strip()
+        if not text:
+            return None
+        if text.endswith("Z"):
+            text = f"{text[:-1]}+00:00"
+        try:
+            parsed = datetime.fromisoformat(text)
+        except ValueError:
+            return None
+    else:
+        return None
+
+    if parsed.tzinfo is None:
+        return parsed.replace(tzinfo=timezone.utc)
+    return parsed.astimezone(timezone.utc)
+
+
+def _get_local_last_modified(
+    config_path: Path, config_data: dict[str, Any]
+) -> Optional[datetime]:
+    parsed = _parse_datetime(config_data.get("LastModifiedOn"))
+    if parsed:
+        return parsed
+    if config_path.exists():
+        return datetime.fromtimestamp(config_path.stat().st_mtime, tz=timezone.utc)
+    return None
+
+
+def _write_glue_job_list_csv(jobs: list[dict[str, Any]], output_path: Path) -> None:
+    fieldnames: list[str] = []
+    for job in jobs:
+        if not isinstance(job, Mapping):
+            continue
+        for key in job.keys():
+            if key not in fieldnames:
+                fieldnames.append(str(key))
+
+    with output_path.open("w", newline="", encoding="utf-8") as handle:
+        if not fieldnames:
+            handle.write("")
+            return
+        writer = csv.DictWriter(handle, fieldnames=fieldnames, extrasaction="ignore")
+        writer.writeheader()
+        for job in jobs:
+            if isinstance(job, Mapping):
+                writer.writerow(job)