Add CLI parameters for cdf data respace plan/execute (#2522)

# Description

Add CLI parameters for `cdf data respace plan/execute`

Define Typer-annotated arguments and options for both subcommands:
- plan: csv_file (positional), --output-file/-o (default:
respace_plan.json)
- execute: plan_file (positional), --backup-dir/-b (required),
--dry-run/-d

Add RespaceMapping and RespaceMappingList data classes for future CSV
input parsing (columns: sourceSpace, externalId, targetSpace). External
ID is preserved — only the space changes. These classes are not yet
wired into the command logic.

## Bump

- [ ] Patch
- [x] Skip

## Changelog

### Changed

-  cognite_toolkit/_cdf_tk/apps/_respace_app.py

What changed: The respace_plan() and respace_execute() methods
previously had no parameters. They now have full Typer-annotated CLI
parameter definitions:

  - `respace_plan()`
Added two parameters:
- `csv_file`: required positional argument pointing to an existing CSV
file. Typer validates that the file exists, is a file (not a directory),
and resolves it to an absolute path. Help text documents the expected
columns: sourceSpace, externalId, targetSpace.
- `output_file`: optional named option (--output-file / -o) defaulting
to respace_plan.json in the current working directory.

Both parameters are forwarded to `RespaceCommand.plan()`.

  - `respace_execute()`
Added three parameters:
- `plan_file`: required positional argument pointing to an existing JSON
plan file, with the same path validation as `csv_file`.
- `backup_dir`: required named option (--backup-dir / -b). No exists
check since the user might pass a directory that doesn't exist yet. The
execute command would create it during execution.
- `dry_run`: optional boolean flag (--dry-run / -d) defaulting to False.

All three parameters are forwarded to `RespaceCommand.execute()`.


-  cognite_toolkit/_cdf_tk/commands/_respace.py

What changed: Two additions: the command methods now accept parameters,
and two new data classes were added for future CSV parsing.
- `RespaceMapping`: A new Pydantic model representing a single row of
the input CSV. It has three required string fields (source_space,
external_id, target_space) with alias_generator=to_camel_case so
camelCase CSV headers (sourceSpace, externalId, targetSpace) map to
snake_case fields. A `model_validator` rejects rows where sourceSpace ==
targetSpace. The external ID is preserved — only the space changes.
- `RespaceMappingList`: A ModelList[RespaceMapping] subclass that
provides CSV schema validation and parsing via the inherited
`read_csv_file()` method. Only implements the required abstract method
`_get_base_model_cls()`. Not yet wired into the command logic.
- `RespaceCommand.plan()`: Signature changed from plan(self) to
plan(self, csv_file: Path, output_file: Path). Prints the received
parameters as confirmation before the placeholder message.
- `RespaceCommand.execute()`: Signature changed from execute(self) to
execute(self, plan_file: Path, backup_dir: Path, dry_run: bool = False).
Prints the received parameters, using the verb-swapping pattern ("Would
execute" / "Executing") to indicate dry run mode, consistent with the
existing codebase style.

---------

Co-authored-by: Iván Surif <ivan.surif@cognite.com>

Author: ivansurif

cognite_toolkit/_cdf_tk/apps/_respace_app.py

@@ -1,4 +1,5 @@
-from typing import Any
+from pathlib import Path
+from typing import Annotated, Any
 
 import typer
 from rich import print
@@ -20,13 +21,59 @@ def main(ctx: typer.Context) -> None:
             print("Use [bold yellow]cdf data respace --help[/] for more information.")
 
     @staticmethod
-    def respace_plan() -> None:
+    def respace_plan(
+        csv_file: Annotated[
+            Path,
+            typer.Argument(
+                help="Path to CSV file with nodes to respace. Expected columns: sourceSpace, externalId, targetSpace.",
+                exists=True,
+                file_okay=True,
+                dir_okay=False,
+                resolve_path=True,
+            ),
+        ],
+        output_file: Annotated[
+            Path,
+            typer.Option(
+                "--output-file",
+                "-o",
+                help="Path for the output plan file.",
+            ),
+        ] = Path("respace_plan.json"),
+    ) -> None:
         """Generate a respace plan by analyzing nodes and their dependencies."""
         cmd = RespaceCommand()
-        cmd.run(lambda: cmd.plan())
+        cmd.run(lambda: cmd.plan(csv_file=csv_file, output_file=output_file))
 
     @staticmethod
-    def respace_execute() -> None:
+    def respace_execute(
+        plan_file: Annotated[
+            Path,
+            typer.Argument(
+                help="Path to the respace plan JSON generated by 'plan' command.",
+                exists=True,
+                file_okay=True,
+                dir_okay=False,
+                resolve_path=True,
+            ),
+        ],
+        backup_dir: Annotated[
+            Path,
+            typer.Option(
+                "--backup-dir",
+                "-b",
+                help="Directory to store backup data before migration.",
+            ),
+        ],
+        dry_run: Annotated[
+            bool,
+            typer.Option(
+                "--dry-run",
+                "-d",
+                help="Preview changes without executing.",
+            ),
+        ] = False,
+    ) -> None:
         """Execute a respace plan, migrating nodes between spaces."""
         cmd = RespaceCommand()
-        cmd.run(lambda: cmd.execute())
+        cmd.run(lambda: cmd.execute(plan_file=plan_file, backup_dir=backup_dir, dry_run=dry_run))

cognite_toolkit/_cdf_tk/commands/_respace.py

@@ -1,10 +1,43 @@
+from pathlib import Path
+
+from cognite.client.utils._text import to_camel_case
+from pydantic import BaseModel, model_validator
 from rich import print
 
 from cognite_toolkit._cdf_tk.client import ToolkitClient
+from cognite_toolkit._cdf_tk.storageio._data_classes import ModelList
 
 from ._base import ToolkitCommand
 
 
+class RespaceMapping(BaseModel, alias_generator=to_camel_case, populate_by_name=True):
+    """A single node respace mapping from source to target.
+
+    The external ID is preserved — only the space changes.
+
+    CSV columns: sourceSpace, externalId, targetSpace
+    """
+
+    source_space: str
+    external_id: str
+    target_space: str
+
+    @model_validator(mode="after")
+    def _target_differs_from_source(self) -> "RespaceMapping":
+        if self.source_space == self.target_space:
+            raise ValueError(
+                f"targetSpace must differ from sourceSpace, "
+                f"but both are '{self.source_space}' for externalId '{self.external_id}'"
+            )
+        return self
+
+
+class RespaceMappingList(ModelList[RespaceMapping]):
+    @classmethod
+    def _get_base_model_cls(cls) -> type[RespaceMapping]:
+        return RespaceMapping
+
+
 class RespaceCommand(ToolkitCommand):
     def __init__(
         self,
@@ -15,10 +48,15 @@ def __init__(
     ):
         super().__init__(print_warning, skip_tracking, silent, client)
 
-    def plan(self) -> None:
+    def plan(self, csv_file: Path, output_file: Path) -> None:
         """Generate a respace plan from a CSV file."""
+        print(f"[bold]Planning respace from:[/] {csv_file}")
+        print(f"[bold]Output plan file:[/] {output_file}")
         print("[bold yellow]:construction: Work in Progress, you'll be able to plan soon! :construction:[/]")
 
-    def execute(self) -> None:
+    def execute(self, plan_file: Path, backup_dir: Path, dry_run: bool = False) -> None:
         """Execute a respace plan."""
+        verb = "Would execute" if dry_run else "Executing"
+        print(f"[bold]{verb} plan:[/] {plan_file}")
+        print(f"[bold]Backup directory:[/] {backup_dir}")
         print("[bold yellow]:construction: Work in Progress, you'll be able to execute soon! :construction:[/]")