Add ELM migrations commands

.flake8

@@ -21,5 +21,8 @@ exclude =
     scripts
     doc
     build_scripts
+    env
+    venv
+    .venv
 	*/test/*
     */devops_sdk/*

.vscode/tasks.json

@@ -3,15 +3,18 @@
     "tasks": [
       {
         "label": "BuildWheel",
-        "command": "${command:python.interpreterPath}",
+        "type": "shell",
+        "command": "python",
         "args": [
           "setup.py",
           "sdist",
           "bdist_wheel"
         ],
-        "type": "shell",
         "options": {
-          "cwd": "${workspaceRoot}/azure-devops/"
+          "cwd": "${workspaceRoot}/azure-devops/",
+          "env": {
+            "PATH": "${workspaceRoot}\\env\\Scripts;${env:PATH}"
+          }
         },
         "presentation": {
             "echo": true,

README.md

@@ -28,6 +28,7 @@ $az [group] [subgroup] [command] {parameters}
 ```
 
 Adding the Azure DevOps Extension adds `devops`, `pipelines`, `artifacts`, `boards` and `repos` groups.
+Enterprise live migrations are available under `az devops migrations`.
 For usage and help content for any command, pass in the -h parameter, for example:
 
 ```bash
@@ -43,6 +44,7 @@ Group
 
 Subgroups:
     admin            : Manage administration operations.
+    migrations       : Manage enterprise live migrations.
     extension        : Manage extensions.
     project          : Manage team projects.
     security         : Manage security related operations.
@@ -64,6 +66,7 @@ Commands:
 - Checkout the CLI docs at [docs.microsoft.com - Azure DevOps CLI](https://docs.microsoft.com/azure/devops/cli/).
 - Check out other examples in the [How-to guides](https://docs.microsoft.com/azure/devops/cli/?view=azure-devops#how-to-guides) section.
 - You can view the various commands and its usage here - [docs.microsoft.com - Azure DevOps Extension Reference](https://docs.microsoft.com/en-us/cli/azure/devops?view=azure-cli-latest)
+- Enterprise live migrations guide: [doc/migrations.md](doc/migrations.md)
 
 ## Contribute
 

azure-devops/azext_devops/__init__.py

@@ -21,6 +21,8 @@ def load_command_table(self, args):
         load_admin_commands(self, args)
         from azext_devops.dev.boards.commands import load_work_commands
         load_work_commands(self, args)
+        from azext_devops.dev.migration.commands import load_migration_commands
+        load_migration_commands(self, args)
         from azext_devops.dev.pipelines.commands import load_build_commands
         load_build_commands(self, args)
         from azext_devops.dev.repos.commands import load_code_commands
@@ -36,6 +38,8 @@ def load_arguments(self, command):
         load_admin_arguments(self, command)
         from azext_devops.dev.boards.arguments import load_work_arguments
         load_work_arguments(self, command)
+        from azext_devops.dev.migration.arguments import load_migration_arguments
+        load_migration_arguments(self, command)
         from azext_devops.dev.pipelines.arguments import load_build_arguments
         load_build_arguments(self, command)
         from azext_devops.dev.repos.arguments import load_code_arguments
@@ -47,8 +51,8 @@ def load_arguments(self, command):
 
     @staticmethod
     def post_parse_args(_cli_ctx, **kwargs):
-        if (kwargs.get('command', None) and
-                kwargs['command'].startswith(('devops', 'boards', 'artifacts', 'pipelines', 'repos'))):
+        command = kwargs.get('command', None)
+        if command and command.startswith(('devops', 'boards', 'artifacts', 'pipelines', 'repos', 'migrations')):
             from azext_devops.dev.common.telemetry import set_tracking_data
             # we need to set tracking data only after we know that all args are valid,
             # otherwise we may log EUII data that a user inadvertently sent as an argument

azure-devops/azext_devops/dev/common/arguments.py

@@ -25,8 +25,7 @@ def convert_date_string_to_iso8601(value, argument=None):
     if d.tzinfo is None:
         from dateutil.tz import tzlocal
         d = d.replace(tzinfo=tzlocal())
-        d = d.isoformat()
-    return d
+    return d.isoformat()
 
 
 def convert_date_only_string_to_iso8601(value, argument=None):

azure-devops/azext_devops/dev/migration/__init__.py

@@ -0,0 +1,8 @@
+# --------------------------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for license information.
+# --------------------------------------------------------------------------------------------
+
+from ._help import load_migration_help
+
+load_migration_help()

azure-devops/azext_devops/dev/migration/_format.py

@@ -0,0 +1,46 @@
+# --------------------------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for license information.
+# --------------------------------------------------------------------------------------------
+
+from collections import OrderedDict
+from azext_devops.dev.common.format import trim_for_display, date_time_to_only_date
+
+
+_TARGET_TRUNCATION_LENGTH = 60
+
+
+def transform_migrations_table_output(result):
+    migrations = _unwrap_migration_list(result)
+    table_output = []
+    for item in migrations:
+        table_output.append(_transform_migration_row(item))
+    return table_output
+
+
+def transform_migration_table_output(result):
+    if result is None:
+        return []
+    return [_transform_migration_row(result)]
+
+
+def _unwrap_migration_list(result):
+    if isinstance(result, dict) and 'value' in result:
+        return result['value']
+    if isinstance(result, list):
+        return result
+    return []
+
+
+def _transform_migration_row(row):
+    table_row = OrderedDict()
+    table_row['RepositoryId'] = row.get('repositoryId')
+    table_row['TargetRepository'] = trim_for_display(row.get('targetRepository'),
+                                                     _TARGET_TRUNCATION_LENGTH)
+    table_row['Status'] = row.get('status')
+    table_row['Stage'] = row.get('stage')
+    table_row['ValidateOnly'] = row.get('validateOnly')
+    table_row['CutoverDate'] = date_time_to_only_date(row.get('scheduledCutoverDate'))
+    table_row['CodeSyncDate'] = date_time_to_only_date(row.get('codeSyncDate'))
+    table_row['PrSyncDate'] = date_time_to_only_date(row.get('pullRequestSyncDate'))
+    return table_row

azure-devops/azext_devops/dev/migration/_help.py

@@ -0,0 +1,91 @@
+# --------------------------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for license information.
+# --------------------------------------------------------------------------------------------
+
+from knack.help_files import helps
+
+
+def load_migration_help():
+    helps['devops migrations'] = """
+    type: group
+    short-summary: Manage enterprise live migrations.
+    long-summary: 'This command group is a part of the azure-devops extension. For ELM migrations, --org should be your Azure DevOps organization URL (for example: https://dev.azure.com/myorg).'
+    """
+
+    helps['devops migrations list'] = """
+    type: command
+    short-summary: List migrations in an organization.
+    examples:
+      - name: List migrations.
+        text: |
+          az devops migrations list --org https://dev.azure.com/myorg
+      - name: List all migrations including inactive ones.
+        text: |
+          az devops migrations list --org https://dev.azure.com/myorg --include-inactive
+    """
+
+    helps['devops migrations status'] = """
+    type: command
+    short-summary: Get migration status for a repository.
+    examples:
+      - name: Get migration status by repository id.
+        text: |
+          az devops migrations status --org https://dev.azure.com/myorg --repository-id 00000000-0000-0000-0000-000000000000
+    """
+
+    helps['devops migrations create'] = """
+    type: command
+    short-summary: Create a migration for a repository.
+    examples:
+      - name: Create a migration.
+        text: |
+          az devops migrations create --org https://dev.azure.com/myorg --repository-id 00000000-0000-0000-0000-000000000000 --target-repository https://github.com/OrgName/RepoName --target-owner-user-id OwnerUserId --agent-pool MigrationPool
+      - name: Create a validate-only migration.
+        text: |
+          az devops migrations create --org https://dev.azure.com/myorg --repository-id 00000000-0000-0000-0000-000000000000 --target-repository https://github.com/OrgName/RepoName --target-owner-user-id OwnerUserId --agent-pool MigrationPool --validate-only --skip-validation ActivePullRequestCount,PullRequestDeltaSize
+    """
+
+    helps['devops migrations pause'] = """
+    type: command
+    short-summary: Pause an active migration.
+    """
+
+    helps['devops migrations resume'] = """
+    type: command
+    short-summary: Resume a stopped (paused, failed) migration.
+    examples:
+      - name: Resume using the current mode.
+        text: |
+          az devops migrations resume --org https://dev.azure.com/myorg --repository-id 00000000-0000-0000-0000-000000000000
+      - name: Resume in validate-only mode.
+        text: |
+          az devops migrations resume --org https://dev.azure.com/myorg --repository-id 00000000-0000-0000-0000-000000000000 --validate-only
+      - name: Continue migration (clears validate-only mode).
+        text: |
+          az devops migrations resume --org https://dev.azure.com/myorg --repository-id 00000000-0000-0000-0000-000000000000 --migration
+    """
+
+    helps['devops migrations abandon'] = """
+    type: command
+    short-summary: Abandon and delete a migration.
+    """
+
+    helps['devops migrations cutover'] = """
+    type: group
+    short-summary: Manage migration cutover.
+    """
+
+    helps['devops migrations cutover set'] = """
+    type: command
+    short-summary: Schedule cutover for a migration.
+    examples:
+      - name: Schedule cutover.
+        text: |
+          az devops migrations cutover set --org https://dev.azure.com/myorg --repository-id 00000000-0000-0000-0000-000000000000 --date 2030-12-31T11:59:00Z
+    """
+
+    helps['devops migrations cutover cancel'] = """
+    type: command
+    short-summary: Cancel a scheduled cutover.
+    """

azure-devops/azext_devops/dev/migration/arguments.py

@@ -0,0 +1,45 @@
+# --------------------------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for license information.
+# --------------------------------------------------------------------------------------------
+
+from azext_devops.dev.common.arguments import convert_date_string_to_iso8601
+from azext_devops.dev.team.arguments import load_global_args
+
+
+# pylint: disable=too-many-statements
+def load_migration_arguments(self, _):
+    with self.argument_context('devops migrations') as context:
+        load_global_args(context)
+        context.argument('repository_id', options_list='--repository-id',
+                         help='ID of the repository (GUID).')
+
+    with self.argument_context('devops migrations list') as context:
+        context.argument('include_inactive', options_list='--include-inactive', action='store_true',
+                         help='Include inactive (completed, abandoned, failed) migrations in the results.')
+
+    with self.argument_context('devops migrations create') as context:
+        context.argument('target_repository', options_list='--target-repository',
+                         help='Target repository URL.')
+        context.argument('target_owner_user_id', options_list='--target-owner-user-id',
+                         help='Target repository owner user ID.')
+        context.argument('validate_only', options_list='--validate-only', action='store_true',
+                         help='Create in validate-only mode (pre-migration checks only).')
+        context.argument('cutover_date', options_list='--cutover-date',
+                         type=convert_date_string_to_iso8601,
+                         help='Scheduled cutover date/time (ISO 8601).')
+        context.argument('agent_pool', options_list='--agent-pool',
+                         help='Agent pool name to use for migration work.')
+        context.argument('skip_validation', options_list='--skip-validation',
+                         help='Comma-separated list of validation policies to skip.')
+
+    with self.argument_context('devops migrations cutover set') as context:
+        context.argument('cutover_date', options_list='--date',
+                         type=convert_date_string_to_iso8601,
+                         help='The date and time for cutover (ISO 8601).')
+
+    with self.argument_context('devops migrations resume') as context:
+        context.argument('validate_only', options_list='--validate-only', action='store_true',
+                         help='Resume in validate-only mode.')
+        context.argument('migration', options_list='--migration', action='store_true',
+                         help='Continue the migration (clears any validate-only mode).')

azure-devops/azext_devops/dev/migration/commands.py

@@ -0,0 +1,29 @@
+# --------------------------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for license information.
+# --------------------------------------------------------------------------------------------
+
+from azure.cli.core.commands import CliCommandType
+from azext_devops.dev.common.exception_handler import azure_devops_exception_handler
+from ._format import transform_migrations_table_output, transform_migration_table_output
+
+
+migrationOps = CliCommandType(
+    operations_tmpl='azext_devops.dev.migration.migration#{}',
+    exception_handler=azure_devops_exception_handler
+)
+
+
+def load_migration_commands(self, _):
+    with self.command_group('devops migrations', command_type=migrationOps) as g:
+        g.command('list', 'list_migrations', table_transformer=transform_migrations_table_output)
+        g.command('status', 'get_migration', table_transformer=transform_migration_table_output)
+        g.command('create', 'create_migration', table_transformer=transform_migration_table_output)
+        g.command('pause', 'pause_migration', table_transformer=transform_migration_table_output)
+        g.command('resume', 'resume_migration', table_transformer=transform_migration_table_output)
+        g.command('abandon', 'delete_migration',
+                  confirmation='Are you sure you want to abandon this migration?')
+
+    with self.command_group('devops migrations cutover', command_type=migrationOps) as g:
+        g.command('set', 'schedule_cutover', table_transformer=transform_migration_table_output)
+        g.command('cancel', 'cancel_cutover', table_transformer=transform_migration_table_output)