nextmv 0.18.0__py3-none-any.whl → 1.0.0.dev2__py3-none-any.whl

nextmv/cli/cloud/secrets/update.py

@@ -0,0 +1,147 @@
+"""
+This module defines the cloud secrets update command for the Nextmv CLI.
+"""
+
+import json
+from typing import Annotated
+
+import typer
+
+from nextmv.cli.cloud.secrets.create import build_secrets
+from nextmv.cli.configuration.config import build_app
+from nextmv.cli.message import enum_values, error, print_json, success
+from nextmv.cli.options import AppIDOption, ProfileOption, SecretsCollectionIDOption
+from nextmv.cloud.secrets import SecretType
+
+# Set up subcommand application.
+app = typer.Typer()
+
+
+@app.command()
+def update(
+    app_id: AppIDOption,
+    secrets_collection_id: SecretsCollectionIDOption,
+    description: Annotated[
+        str | None,
+        typer.Option(
+            "--description",
+            "-d",
+            help="A new description for the secrets collection.",
+            metavar="DESCRIPTION",
+        ),
+    ] = None,
+    name: Annotated[
+        str | None,
+        typer.Option(
+            "--name",
+            "-n",
+            help="A new name for the secrets collection.",
+            metavar="NAME",
+        ),
+    ] = None,
+    output: Annotated[
+        str | None,
+        typer.Option(
+            "--output",
+            "-u",
+            help="Saves the updated secrets collection information to this location.",
+            metavar="OUTPUT_PATH",
+        ),
+    ] = None,
+    secrets: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--secrets",
+            "-e",
+            help="Secrets to configure in the app. Data should be valid [magenta]json[/magenta]. "
+            "Pass multiple secrets by repeating the flag, or providing a list of objects. "
+            "Allowed values for [magenta]type[/magenta] are: "
+            f"{enum_values(SecretType)}. "
+            "Object format: [green]{'type': type, 'location': location, 'value': value}[/green]. "
+            "This will replace all existing secrets in the collection.",
+            metavar="SECRETS",
+        ),
+    ] = None,
+    profile: ProfileOption = None,
+) -> None:
+    """
+    Update a Nextmv Cloud secrets collection.
+
+    You can update the name, description, and/or secrets of an existing
+    secrets collection. When updating secrets, all existing secrets will be
+    replaced with the new ones provided.
+
+    Secrets are provided as JSON objects using the [code]--secrets[/code] flag,
+    following the same format as the create command. You can provide secrets as:
+    - A single secret as a JSON object
+    - Multiple secrets by repeating the [code]--secrets[/code] flag
+    - Multiple secrets as a JSON array in a single [code]--secrets[/code] flag
+
+    [bold][underline]Examples[/underline][/bold]
+
+    - Update the name of a secrets collection.
+        $ [green]nextmv cloud secrets update --app-id hare-app \\
+            --secrets-collection-id api-keys --name "Updated API Keys"[/green]
+
+    - Update the description of a secrets collection.
+        $ [green]nextmv cloud secrets update --app-id hare-app \\
+            --secrets-collection-id api-keys \\
+            --description "Updated collection of API keys"[/green]
+
+    - Update both name and description.
+        $ [green]nextmv cloud secrets update --app-id hare-app \\
+            --secrets-collection-id api-keys --name "Production API Keys" \\
+            --description "API keys for production environment"[/green]
+
+    - Replace all secrets in a collection with new secrets.
+        $ [green]nextmv cloud secrets update --app-id hare-app \\
+            --secrets-collection-id api-keys \\
+            --secrets '{"type": "env", "location": "API_KEY", "value": "new-value"}' \\
+            --secrets '{"type": "env", "location": "DATABASE_URL", "value": "postgres://newhost"}'[/green]
+
+    - Replace all secrets with a JSON array.
+        $ [green]nextmv cloud secrets update --app-id hare-app \\
+            --secrets-collection-id api-keys \\
+            --secrets '[{"type": "env", "location": "API_KEY", "value": "new-value"}, {...}]'[/green]
+
+    - Update multiple attributes at once and save the result.
+        $ [green]nextmv cloud secrets update --app-id hare-app \\
+            --secrets-collection-id api-keys --name "New Name" \\
+            --description "New Description" \\
+            --secrets '{"type": "env", "location": "NEW_KEY", "value": "new-value"}' \\
+            --output updated.json[/green]
+    """
+
+    if name is None and description is None and secrets is None:
+        error(
+            "Provide at least one option to update: "
+            "[code]--name[/code], [code]--description[/code], or [code]--secrets[/code]."
+        )
+
+    cloud_app = build_app(app_id=app_id, profile=profile)
+
+    # Build the secrets list if provided
+    secrets_list = None
+    if secrets is not None:
+        secrets_list = build_secrets(secrets)
+
+    collection = cloud_app.update_secrets_collection(
+        secrets_collection_id=secrets_collection_id,
+        name=name,
+        description=description,
+        secrets=secrets_list,
+    )
+    success(
+        f"Secrets collection [magenta]{secrets_collection_id}[/magenta] updated successfully "
+        f"in application [magenta]{app_id}[/magenta]."
+    )
+
+    if output is not None and output != "":
+        with open(output, "w") as f:
+            json.dump(collection.to_dict(), f, indent=2)
+
+        success(msg=f"Updated secrets collection information saved to [magenta]{output}[/magenta].")
+
+        return
+
+    print_json(collection.to_dict())

nextmv/cli/cloud/shadow/__init__.py

@@ -0,0 +1,33 @@
+"""
+This module defines the cloud batch command tree for the Nextmv CLI.
+"""
+
+import typer
+
+from nextmv.cli.cloud.shadow.create import app as create_app
+from nextmv.cli.cloud.shadow.delete import app as delete_app
+from nextmv.cli.cloud.shadow.get import app as get_app
+from nextmv.cli.cloud.shadow.list import app as list_app
+from nextmv.cli.cloud.shadow.metadata import app as metadata_app
+from nextmv.cli.cloud.shadow.start import app as start_app
+from nextmv.cli.cloud.shadow.stop import app as stop_app
+from nextmv.cli.cloud.shadow.update import app as update_app
+
+# Set up subcommand application.
+app = typer.Typer()
+app.add_typer(create_app)
+app.add_typer(delete_app)
+app.add_typer(get_app)
+app.add_typer(list_app)
+app.add_typer(metadata_app)
+app.add_typer(start_app)
+app.add_typer(stop_app)
+app.add_typer(update_app)
+
+
+@app.callback()
+def callback() -> None:
+    """
+    Create and manage Nextmv Cloud shadow tests.
+    """
+    pass

nextmv/cli/cloud/shadow/create.py

@@ -0,0 +1,184 @@
+"""
+This module defines the cloud shadow create command for the Nextmv CLI.
+"""
+
+import json
+from datetime import datetime
+from typing import Annotated
+
+import typer
+
+from nextmv.cli.configuration.config import build_app
+from nextmv.cli.message import error, in_progress, print_json
+from nextmv.cli.options import AppIDOption, ProfileOption
+from nextmv.cloud.shadow import StartEvents, TerminationEvents
+
+# Set up subcommand application.
+app = typer.Typer()
+
+
+@app.command()
+def create(
+    app_id: AppIDOption,
+    comparisons: Annotated[
+        str,
+        typer.Option(
+            "--comparisons",
+            "-c",
+            help="Object mapping baseline instance IDs to a list of comparison instance IDs. "
+            "Data should be valid [magenta]json[/magenta]. "
+            "Object format: [green]{'baseline_id1': ['comparison_id1', 'comparison_id2'], 'baseline_id2': ...}[/green]",
+            metavar="COMPARISONS",
+        ),
+    ],
+    termination_maximum_runs: Annotated[
+        int,
+        typer.Option(
+            "--termination-maximum-runs",
+            "-m",
+            help="Maximum number of runs for the shadow test termination condition. Must be at least 1.",
+            metavar="TERMINATION_MAXIMUM_RUNS",
+        ),
+    ],
+    description: Annotated[
+        str | None,
+        typer.Option(
+            "--description",
+            "-d",
+            help="Description of the shadow test.",
+            metavar="DESCRIPTION",
+        ),
+    ] = None,
+    name: Annotated[
+        str | None,
+        typer.Option(
+            "--name",
+            "-n",
+            help="Name of the shadow test. If not provided, the ID will be used as the name.",
+            metavar="NAME",
+        ),
+    ] = None,
+    shadow_test_id: Annotated[
+        str | None,
+        typer.Option(
+            "--shadow-test-id",
+            "-s",
+            help="ID for the shadow test. Will be generated if not provided.",
+            envvar="NEXTMV_SHADOW_TEST_ID",
+            metavar="SHADOW_TEST_ID",
+        ),
+    ] = None,
+    start_time: Annotated[
+        datetime | None,
+        typer.Option(
+            "--start-time",
+            "-r",
+            formats=["%Y-%m-%dT%H:%M:%S%z"],
+            help="Scheduled time for shadow test start in [magenta]RFC 3339[/magenta] format. "
+            "Example: [magenta]'2024-01-01T00:00:00Z'[/magenta]",
+            metavar="START_TIME",
+        ),
+    ] = None,
+    termination_time: Annotated[
+        datetime | None,
+        typer.Option(
+            "--termination-time",
+            "-t",
+            help="Scheduled time for shadow test end in [magenta]RFC 3339[/magenta] format. "
+            "Example: [magenta]'2024-01-01T00:00:00Z'[/magenta]",
+            formats=["%Y-%m-%dT%H:%M:%S%z"],
+            metavar="TERMINATION_TIME",
+        ),
+    ] = None,
+    profile: ProfileOption = None,
+) -> None:
+    """
+    Create a new Nextmv Cloud shadow test in draft mode.
+
+    Use the [code]--comparisons[/code] option to define how to set up instance
+    comparisons. The value should be valid [magenta]json[/magenta]. The keys of
+    the comparisons object are the baseline instance IDs, and the values
+    are the candidate lists of instance IDs to compare against the respective
+    baseline.
+
+    Here is an example comparisons object:
+    [green]{
+        "baseline-instance-1": ["candidate-instance-1", "candidate-instance-2"],
+        "baseline-instance-2": ["candidate-instance-3"]
+    }[/green]
+
+    You may specify the [code]--start-time[/code] option to make the shadow
+    test start at a specific time. Alternatively, you may use the
+    [code]nextmv cloud shadow start[/code] command to start the test.
+
+    The [code]--termination-maximum-runs[/code] option is required and provides
+    control over when the shadow test should terminate, after said number of
+    runs. Alternatively, you may specify the [code]--termination-time[/code]
+    option or use the [code]nextmv cloud shadow stop[/code] command to stop the
+    test
+
+    [bold][underline]Examples[/underline][/bold]
+
+    - Create a shadow test with a baseline and two candidate instances:
+        $ [green]COMPARISONS='{
+            "fluffy-bunny-baseline": [
+                "hopping-candidate-ears",
+                "speedy-cottontail"
+            ]
+        }'
+        nextmv cloud shadow create --app-id hare-app --shadow-test-id bunny-hop-shadow --name "Bunny Hop Showdown" \\
+            --comparisons "$COMPARISONS" --termination-maximum-runs 100[/green]
+
+    - Create a shadow test with multiple baselines and candidates:
+        $ [green]COMPARISONS='{
+            "fluffy-bunny-baseline": [
+                "hopping-candidate-ears"
+            ],
+            "wise-old-rabbit": [
+                "burrow-master"
+            ]
+        }'
+        nextmv cloud shadow create --app-id hare-app --shadow-test-id warren-race --name "Warren Race Test" \\
+            --comparisons "$COMPARISONS" --termination-maximum-runs 50[/green]
+
+    - Create a shadow test with a scheduled start and termination time:
+        $ [green]COMPARISONS='{
+            "fluffy-bunny-baseline": [
+                "hopping-candidate-ears"
+            ]
+        }'
+        nextmv cloud shadow create --app-id hare-app --shadow-test-id sunrise-hop --name "Sunrise Hop Test" \\
+            --comparisons "$COMPARISONS" --start-time '2026-01-23T10:00:00Z' \\
+            --termination-time '2026-01-23T18:00:00Z' --termination-maximum-runs 20[/green]
+
+    - Create a shadow test with a description:
+        $ [green]COMPARISONS='{
+            "fluffy-bunny-baseline": [
+                "hopping-candidate-ears"
+            ]
+        }'
+        nextmv cloud shadow create --app-id hare-app --shadow-test-id carrot-compare --name "Carrot Comparison" \\
+            --description "Testing cool bunnies" --comparisons "$COMPARISONS" --termination-maximum-runs 10[/green]
+    """
+
+    cloud_app = build_app(app_id=app_id, profile=profile)
+
+    try:
+        comparisons_dict = json.loads(comparisons)
+    except json.JSONDecodeError as e:
+        error(f"Invalid comparisons format: [magenta]{comparisons}[/magenta]. Error: {e}")
+
+    in_progress(msg="Creating shadow test...")
+    shadow_test = cloud_app.new_shadow_test(
+        comparisons=comparisons_dict,
+        termination_events=TerminationEvents(
+            maximum_runs=termination_maximum_runs,
+            time=termination_time,
+        ),
+        shadow_test_id=shadow_test_id,
+        name=name,
+        description=description,
+        start_events=StartEvents(time=start_time) if start_time is not None else None,
+    )
+
+    print_json(shadow_test.to_dict())

nextmv/cli/cloud/shadow/delete.py

@@ -0,0 +1,68 @@
+"""
+This module defines the cloud shadow delete command for the Nextmv CLI.
+"""
+
+from typing import Annotated
+
+import typer
+from rich.prompt import Confirm
+
+from nextmv.cli.configuration.config import build_app
+from nextmv.cli.message import info, success
+from nextmv.cli.options import AppIDOption, ProfileOption, ShadowTestIDOption
+
+# Set up subcommand application.
+app = typer.Typer()
+
+
+@app.command()
+def delete(
+    app_id: AppIDOption,
+    shadow_test_id: ShadowTestIDOption,
+    yes: Annotated[
+        bool,
+        typer.Option(
+            "--yes",
+            "-y",
+            help="Agree to deletion confirmation prompt. Useful for non-interactive sessions.",
+        ),
+    ] = False,
+    profile: ProfileOption = None,
+) -> None:
+    """
+    Deletes a Nextmv Cloud shadow test.
+
+    This action is permanent and cannot be undone. The shadow test and all
+    associated data, including runs, will be deleted. Use the [code]--yes[/code]
+    flag to skip the confirmation prompt.
+
+    [bold][underline]Examples[/underline][/bold]
+
+    - Delete the shadow test with the ID [magenta]hop-analysis[/magenta] from application
+      [magenta]hare-app[/magenta].
+        $ [green]nextmv cloud shadow delete --app-id hare-app --shadow-test-id hop-analysis[/green]
+
+    - Delete the shadow test without confirmation prompt.
+        $ [green]nextmv cloud shadow delete --app-id hare-app --shadow-test-id carrot-routes --yes[/green]
+    """
+
+    if not yes:
+        confirm = Confirm.ask(
+            f"Are you sure you want to delete shadow test [magenta]{shadow_test_id}[/magenta] "
+            f"from application [magenta]{app_id}[/magenta]? This action cannot be undone.",
+            default=False,
+        )
+
+        if not confirm:
+            info(
+                msg=f"Shadow test [magenta]{shadow_test_id}[/magenta] will not be deleted.",
+                emoji=":bulb:",
+            )
+            return
+
+    cloud_app = build_app(app_id=app_id, profile=profile)
+    cloud_app.delete_shadow_test(shadow_test_id=shadow_test_id)
+    success(
+        f"Shadow test [magenta]{shadow_test_id}[/magenta] deleted successfully "
+        f"from application [magenta]{app_id}[/magenta]."
+    )

nextmv/cli/cloud/shadow/get.py

@@ -0,0 +1,61 @@
+"""
+This module defines the cloud shadow get command for the Nextmv CLI.
+"""
+
+import json
+from typing import Annotated
+
+import typer
+
+from nextmv.cli.configuration.config import build_app
+from nextmv.cli.message import in_progress, print_json, success
+from nextmv.cli.options import AppIDOption, ProfileOption, ShadowTestIDOption
+
+# Set up subcommand application.
+app = typer.Typer()
+
+
+@app.command()
+def get(
+    app_id: AppIDOption,
+    shadow_test_id: ShadowTestIDOption,
+    output: Annotated[
+        str | None,
+        typer.Option(
+            "--output",
+            "-o",
+            help="Saves the results to this location.",
+            metavar="OUTPUT_PATH",
+        ),
+    ] = None,
+    profile: ProfileOption = None,
+) -> None:
+    """
+    Get a Nextmv Cloud shadow test, including its runs.
+
+    [bold][underline]Examples[/underline][/bold]
+
+    - Get the shadow test with ID [magenta]carrot-optimization[/magenta] from application
+      [magenta]hare-app[/magenta].
+        $ [green]nextmv cloud shadow get --app-id hare-app --shadow-test-id carrot-optimization[/green]
+
+    - Get the shadow test using a specific profile.
+        $ [green]nextmv cloud shadow get --app-id hare-app --shadow-test-id lettuce-routes --profile prod[/green]
+    """
+
+    cloud_app = build_app(app_id=app_id, profile=profile)
+    in_progress(msg="Getting shadow test...")
+    shadow_test = cloud_app.shadow_test(shadow_test_id=shadow_test_id)
+
+    shadow_test_dict = shadow_test.to_dict()
+
+    # Handle output
+    if output is not None and output != "":
+        with open(output, "w") as f:
+            json.dump(shadow_test_dict, f, indent=2)
+
+        success(msg=f"Shadow test output saved to [magenta]{output}[/magenta].")
+
+        return
+
+    print_json(shadow_test_dict)

nextmv/cli/cloud/shadow/list.py

@@ -0,0 +1,63 @@
+"""
+This module defines the cloud shadow list command for the Nextmv CLI.
+"""
+
+import json
+from typing import Annotated
+
+import typer
+
+from nextmv.cli.configuration.config import build_app
+from nextmv.cli.message import in_progress, print_json, success
+from nextmv.cli.options import AppIDOption, ProfileOption
+
+# Set up subcommand application.
+app = typer.Typer()
+
+
+@app.command()
+def list(
+    app_id: AppIDOption,
+    output: Annotated[
+        str | None,
+        typer.Option(
+            "--output",
+            "-o",
+            help="Saves the list of shadow tests to this location.",
+            metavar="OUTPUT_PATH",
+        ),
+    ] = None,
+    profile: ProfileOption = None,
+) -> None:
+    """
+    List all Nextmv Cloud shadow tests for an application.
+
+    This command retrieves all shadow tests associated with the specified
+    application.
+
+    [bold][underline]Examples[/underline][/bold]
+
+    - List all shadow tests for application [magenta]hare-app[/magenta].
+        $ [green]nextmv cloud shadow list --app-id hare-app[/green]
+
+    - List all shadow tests and save to a file.
+        $ [green]nextmv cloud shadow list --app-id hare-app --output tests.json[/green]
+
+    - List all shadow tests using a specific profile.
+        $ [green]nextmv cloud shadow list --app-id hare-app --profile prod[/green]
+    """
+
+    cloud_app = build_app(app_id=app_id, profile=profile)
+    in_progress(msg="Listing shadow tests...")
+    shadow_tests = cloud_app.list_shadow_tests()
+    shadow_tests_dict = [test.to_dict() for test in shadow_tests]
+
+    if output is not None and output != "":
+        with open(output, "w") as f:
+            json.dump(shadow_tests_dict, f, indent=2)
+
+        success(msg=f"Shadow tests list saved to [magenta]{output}[/magenta].")
+
+        return
+
+    print_json(shadow_tests_dict)

nextmv/cli/cloud/shadow/metadata.py

@@ -0,0 +1,66 @@
+"""
+This module defines the cloud shadow metadata command for the Nextmv CLI.
+"""
+
+import json
+from typing import Annotated
+
+import typer
+
+from nextmv.cli.configuration.config import build_app
+from nextmv.cli.message import in_progress, print_json, success
+from nextmv.cli.options import AppIDOption, ProfileOption, ShadowTestIDOption
+
+# Set up subcommand application.
+app = typer.Typer()
+
+
+@app.command()
+def metadata(
+    app_id: AppIDOption,
+    shadow_test_id: ShadowTestIDOption,
+    output: Annotated[
+        str | None,
+        typer.Option(
+            "--output",
+            "-o",
+            help="Saves the shadow test metadata to this location.",
+            metavar="OUTPUT_PATH",
+        ),
+    ] = None,
+    profile: ProfileOption = None,
+) -> None:
+    """
+    Get metadata for a Nextmv Cloud shadow test.
+
+    This command retrieves metadata for a specific shadow test, including
+    status, creation date, and other high-level information without the full
+    run details.
+
+    [bold][underline]Examples[/underline][/bold]
+
+    - Get metadata for shadow test [magenta]bunny-warren-optimization[/magenta] from application
+      [magenta]hare-app[/magenta].
+        $ [green]nextmv cloud shadow metadata --app-id hare-app --shadow-test-id bunny-warren-optimization[/green]
+
+    - Get metadata and save to a file.
+        $ [green]nextmv cloud shadow metadata --app-id hare-app --shadow-test-id lettuce-delivery \\
+            --output metadata.json[/green]
+
+    - Get metadata using a specific profile.
+        $ [green]nextmv cloud shadow metadata --app-id hare-app --shadow-test-id hop-schedule --profile prod[/green]
+    """
+
+    cloud_app = build_app(app_id=app_id, profile=profile)
+    in_progress(msg="Getting shadow test metadata...")
+    shadow_metadata = cloud_app.shadow_test_metadata(shadow_test_id=shadow_test_id)
+    shadow_metadata_dict = shadow_metadata.to_dict()
+
+    if output is not None and output != "":
+        with open(output, "w") as f:
+            json.dump(shadow_metadata_dict, f, indent=2)
+
+        success(msg=f"Shadow test metadata saved to [magenta]{output}[/magenta].")
+        return
+
+    print_json(shadow_metadata_dict)

nextmv/cli/cloud/shadow/start.py

@@ -0,0 +1,43 @@
+"""
+This module defines the cloud shadow start command for the Nextmv CLI.
+"""
+
+import typer
+
+from nextmv.cli.configuration.config import build_app
+from nextmv.cli.message import in_progress, success
+from nextmv.cli.options import AppIDOption, ProfileOption, ShadowTestIDOption
+
+# Set up subcommand application.
+app = typer.Typer()
+
+
+@app.command()
+def start(
+    app_id: AppIDOption,
+    shadow_test_id: ShadowTestIDOption,
+    profile: ProfileOption = None,
+) -> None:
+    """
+    Starts a Nextmv Cloud shadow test.
+
+    Before starting a shadow test, it must be created in draft state. You may
+    use the [code]nextmv cloud shadow create[/code] command to create a new
+    shadow test. Alternatively, define a [code]--start-time[/code] when using
+    the [code]nextmv cloud shadow create[/code] command to have the shadow test
+    start automatically at a specific time.
+
+    [bold][underline]Examples[/underline][/bold]
+
+    - Start the shadow test with the ID [magenta]hop-analysis[/magenta] from application
+      [magenta]hare-app[/magenta].
+        $ [green]nextmv cloud shadow start --app-id hare-app --shadow-test-id hop-analysis[/green]
+    """
+
+    in_progress(msg="Starting shadow test...")
+    cloud_app = build_app(app_id=app_id, profile=profile)
+    cloud_app.start_shadow_test(shadow_test_id=shadow_test_id)
+    success(
+        f"Shadow test [magenta]{shadow_test_id}[/magenta] started successfully "
+        f"in application [magenta]{app_id}[/magenta]."
+    )