Add basic remote commands

Author: sfc-gh-zzhu

src/snowflake/cli/_plugins/remote/commands.py

@@ -15,36 +15,163 @@
 from __future__ import annotations
 
 import logging
+from typing import List, Optional
 
+import typer
+from snowflake.cli._plugins.remote.manager import RemoteManager
 from snowflake.cli.api.commands.snow_typer import SnowTyperFactory
+from snowflake.cli.api.console import cli_console as cc
+from snowflake.cli.api.output.types import (
+    CommandResult,
+    QueryResult,
+    SingleQueryResult,
+)
 
-log = logging.getLogger(__name__)
 app = SnowTyperFactory(
     name="remote",
-    help="Manages remote development environments.",
+    help="Manages remote development environments on top of Snowpark Container Service.",
+    short_help="Manages remote development environments.",
+)
+
+log = logging.getLogger(__name__)
+
+# Define argument for remote service names (accepts both customer names and full service names)
+RemoteNameArgument = typer.Argument(
+    help="Remote service name. Can be either a customer name (e.g., 'myproject') or full service name (e.g., 'SNOW_REMOTE_admin_myproject')",
+    show_default=False,
 )
 
 
 @app.command("start", requires_connection=True)
-def start_service(**options) -> None:
+def start(
+    name: Optional[str] = typer.Argument(
+        None,
+        help="Service name to resume, or leave empty to create a new service with auto-generated name",
+    ),
+    compute_pool: Optional[str] = typer.Option(
+        None,
+        "--compute-pool",
+        help="Name of the compute pool to use (required for new service creation)",
+        show_default=False,
+    ),
+    eai_name: Optional[List[str]] = typer.Option(
+        None,
+        "--eai-name",
+        help="List of external access integration names to enable network access to external resources",
+    ),
+    stage: Optional[str] = typer.Option(
+        None,
+        "--stage",
+        help="Internal Snowflake stage to mount (e.g., @my_stage or @my_stage/folder).",
+    ),
+    image: Optional[str] = typer.Option(
+        None,
+        "--image",
+        help="Custom image to use (can be full path like 'repo/image:tag' or just tag like '1.7.1')",
+    ),
+    **options,
+) -> None:
     """
-    Start a remote development environment.
+    Starts a remote development environment.
+
+    This command creates a new VS Code Server remote development environment if it doesn't exist,
+    or starts an existing one if it's suspended. If the environment is already running, it's a no-op.
+    The environment is deployed as a Snowpark Container Service that provides
+    a web-based development environment.
+
+    Usage examples:
+    - Resume existing service: snow remote start myproject
+    - Create new service: snow remote start --compute-pool my_pool
+    - Create named service: snow remote start myproject --compute-pool my_pool
 
-    This is a placeholder command for the remote plugin.
-    Full functionality will be implemented in subsequent PRs.
+    The --compute-pool parameter is only required when creating a new service. For resuming
+    existing services, the compute pool is not needed.
     """
-    log.info("Start command called - functionality coming soon!")
-    log.info("Full functionality will be available in upcoming releases.")
+    try:
+        manager = RemoteManager()
+
+        service_name, url, status = manager.start(
+            name=name,
+            compute_pool=compute_pool,
+            external_access=eai_name,
+            stage=stage,
+            image=image,
+        )
+
+        # Display appropriate success message based on what happened
+        if status == "created":
+            cc.message(
+                f"✓ Remote Development Environment {service_name} created successfully!"
+            )
+        elif status == "resumed":
+            cc.message(
+                f"✓ Remote Development Environment {service_name} resumed successfully!"
+            )
+        elif status == "running":
+            cc.message(
+                f"✓ Remote Development Environment {service_name} is already running."
+            )
+
+        cc.message(f"VS Code Server URL: {url}")
+
+        # Log detailed information at debug level
+        if stage:
+            log.debug("Stage '%s' mounted:", stage)
+            log.debug(
+                "  - Workspace: '%s/user-default' → '%s'",
+                stage,
+                "/home/user/workspace",
+            )
+            log.debug(
+                "  - VS Code data: '%s/.vscode-server/data' → '%s'",
+                stage,
+                "/home/user/.vscode-server",
+            )
+        if eai_name:
+            log.debug("External access integrations: %s", ", ".join(eai_name))
+        if image:
+            log.debug("Using custom image: %s", image)
+
+    except ValueError as e:
+        cc.warning(f"Error: {e}")
+        raise typer.Exit(code=1)
+    except Exception as e:
+        cc.warning(f"Error starting remote environment: {e}")
+        raise typer.Exit(code=1)
 
 
 @app.command("list", requires_connection=True)
-def list_services(**options) -> None:
+def list_services(**options) -> CommandResult:
+    """
+    Lists all remote development environments.
+    """
+    cursor = RemoteManager().list_services()
+    return QueryResult(cursor)
+
+
+@app.command("stop", requires_connection=True)
+def stop(
+    name: str = RemoteNameArgument,
+    **options,
+) -> CommandResult:
+    """
+    Suspends a remote development environment.
     """
-    List remote development environments.
+    manager = RemoteManager()
+    cursor = manager.stop(name)
+    cc.message(f"Remote environment '{name}' suspended successfully.")
+    return SingleQueryResult(cursor)
 
-    This is a placeholder command for the remote plugin.
-    Full functionality will be implemented in subsequent PRs.
+
+@app.command("delete", requires_connection=True)
+def delete(
+    name: str = RemoteNameArgument,
+    **options,
+) -> CommandResult:
+    """
+    Deletes a remote development environment.
     """
-    log.info("Remote plugin registered successfully")
-    log.info("Remote development environments plugin is registered.")
-    log.info("Full functionality will be available in upcoming releases.")
+    manager = RemoteManager()
+    cursor = manager.delete(name)
+    cc.message(f"Remote environment '{name}' deleted successfully.")
+    return SingleQueryResult(cursor)

src/snowflake/cli/_plugins/remote/constants.py

@@ -54,24 +54,31 @@ class ComputeResources:
 # Service naming constants
 SERVICE_NAME_PREFIX = "SNOW_REMOTE"
 
-# Service status constants
-SERVICE_STATUS_READY = "READY"
-SERVICE_STATUS_SUSPENDED = "SUSPENDED"
-SERVICE_STATUS_SUSPENDING = "SUSPENDING"
-SERVICE_STATUS_PENDING = "PENDING"
-SERVICE_STATUS_STARTING = "STARTING"
-SERVICE_STATUS_FAILED = "FAILED"
-SERVICE_STATUS_ERROR = "ERROR"
-SERVICE_STATUS_UNKNOWN = "UNKNOWN"
-
-# Service operation result constants
-SERVICE_RESULT_CREATED = "created"
-SERVICE_RESULT_RESUMED = "resumed"
-SERVICE_RESULT_RUNNING = "running"
+
+class ServiceStatus(enum.Enum):
+    """Service status values returned by SHOW SERVICES and SPCS_WAIT_FOR (service-level)."""
+
+    PENDING = "PENDING"
+    RUNNING = "RUNNING"
+    FAILED = "FAILED"
+    DONE = "DONE"
+    SUSPENDING = "SUSPENDING"
+    SUSPENDED = "SUSPENDED"
+    DELETING = "DELETING"
+    DELETED = "DELETED"
+    INTERNAL_ERROR = "INTERNAL_ERROR"
+
+
+class ServiceResult(enum.Enum):
+    """Service operation result values."""
+
+    CREATED = "created"
+    RESUMED = "resumed"
+    RUNNING = "running"
+
 
 # Default timeout for service operations
 DEFAULT_SERVICE_TIMEOUT_MINUTES = 10
-STATUS_CHECK_INTERVAL_SECONDS = 10
 
 # Default container image information
 DEFAULT_IMAGE_REPO = "/snowflake/images/snowflake_images"

src/snowflake/cli/_plugins/remote/container_spec.py

@@ -47,22 +47,32 @@
     ImageSpec,
     format_stage_path,
     get_node_resources,
+    parse_image_string,
 )
 
 
 def _get_image_spec(
-    session: snowpark.Session, compute_pool: str, image_tag: Optional[str] = None
+    session: snowpark.Session, compute_pool: str, image: Optional[str] = None
 ) -> ImageSpec:
     """Get appropriate image specification based on compute pool."""
     # Retrieve compute pool node resources
     resources = get_node_resources(session, compute_pool=compute_pool)
 
-    # Use MLRuntime image - select CPU or GPU based on resources
-    image_repo = DEFAULT_IMAGE_REPO
-    image_name = DEFAULT_IMAGE_GPU if resources.gpu > 0 else DEFAULT_IMAGE_CPU
-
-    # Use provided image_tag or fall back to default
-    if not image_tag:
+    # Set defaults
+    default_image_name = DEFAULT_IMAGE_GPU if resources.gpu > 0 else DEFAULT_IMAGE_CPU
+
+    if image:
+        # Parse the image string
+        parsed_repo, parsed_image_name, parsed_tag = parse_image_string(image)
+
+        # Use parsed values or fall back to defaults
+        image_repo = parsed_repo or DEFAULT_IMAGE_REPO
+        image_name = parsed_image_name or default_image_name
+        image_tag = parsed_tag or DEFAULT_IMAGE_TAG
+    else:
+        # Use all defaults
+        image_repo = DEFAULT_IMAGE_REPO
+        image_name = default_image_name
         image_tag = DEFAULT_IMAGE_TAG
 
     return ImageSpec(
@@ -78,7 +88,7 @@ def generate_service_spec(
     session: snowpark.Session,
     compute_pool: str,
     stage: Optional[str] = None,
-    image_tag: Optional[str] = None,
+    image: Optional[str] = None,
     ssh_public_key: Optional[str] = None,
 ) -> Dict[str, Any]:
     """
@@ -88,7 +98,7 @@ def generate_service_spec(
         session: Snowflake session
         compute_pool: Compute pool for service execution
         stage: Optional internal Snowflake stage to mount (e.g., @my_stage)
-        image_tag: Optional custom image tag to use
+        image: Optional custom image (can be full path like 'repo/image:tag' or just tag like '1.7.1')
         ssh_public_key: Optional SSH public key to inject for secure authentication
 
     Returns:
@@ -99,7 +109,7 @@ def generate_service_spec(
         # Normalize and validate the stage path (raises ValueError if invalid)
         stage = format_stage_path(stage)
 
-    image_spec = _get_image_spec(session, compute_pool, image_tag)
+    image_spec = _get_image_spec(session, compute_pool, image)
 
     # Set resource requests/limits
     # This is a temporary fix to SPCS preprod8 bug to ensure the container has enough memory.
@@ -273,7 +283,7 @@ def generate_service_spec_yaml(
     session: snowpark.Session,
     compute_pool: str,
     stage: Optional[str] = None,
-    image_tag: Optional[str] = None,
+    image: Optional[str] = None,
     ssh_public_key: Optional[str] = None,
 ) -> str:
     """
@@ -285,7 +295,7 @@ def generate_service_spec_yaml(
         session: Snowflake session
         compute_pool: Compute pool for service execution
         stage: Optional internal Snowflake stage to mount (e.g., @my_stage)
-        image_tag: Optional custom image tag to use
+        image: Optional custom image (can be full path like 'repo/image:tag' or just tag like '1.7.1')
         ssh_public_key: Optional SSH public key to inject for secure authentication
 
     Returns:
@@ -295,7 +305,7 @@ def generate_service_spec_yaml(
         session=session,
         compute_pool=compute_pool,
         stage=stage,
-        image_tag=image_tag,
+        image=image,
         ssh_public_key=ssh_public_key,
     )
     return yaml.dump(spec, default_flow_style=False)