systemlink-cli 1.3.1__py3-none-any.whl

slcli/dff_decorators.py

@@ -0,0 +1,24 @@
+"""Decorators and helpers for Dynamic Form Fields (DFF) testing and CLI behavior.
+
+This module provides lightweight decorator utilities used by the CLI tests and
+command implementations. Keep implementations minimal and well-typed.
+"""
+
+from typing import Callable, TypeVar
+
+F = TypeVar("F", bound=Callable[..., object])
+
+
+def passthrough_decorator(func: F) -> F:
+    """A no-op decorator used in testing to preserve function metadata.
+
+    Returns the original function unchanged. Useful as a placeholder when a
+    decorator is required by test scaffolding but implements no behavior.
+
+    Args:
+        func: The callable to return.
+
+    Returns:
+        The original callable ``func``.
+    """
+    return func

slcli/example_click.py

@@ -0,0 +1,404 @@
+"""CLI commands for managing example configurations."""
+
+import json
+import sys
+from typing import Any, Dict, List, Optional
+
+import click
+
+from .example_loader import ExampleLoader
+from .example_provisioner import ExampleProvisioner, ProvisioningAction, ProvisioningResult
+from .universal_handlers import UniversalResponseHandler, FilteredResponse
+from .utils import ExitCodes, format_success, get_workspace_map, handle_api_error, save_json_file
+from .workspace_utils import get_effective_workspace
+
+
+def _resolve_workspace_id(workspace: Optional[str]) -> Optional[str]:
+    """Resolve workspace name to ID using workspace map.
+
+    Args:
+        workspace: Workspace name or ID provided by the user.
+
+    Returns:
+        Workspace ID if resolved; original value if already an ID; None if not provided.
+    """
+    if not workspace:
+        return None
+
+    workspace_map = get_workspace_map()
+    if not workspace_map:
+        return workspace
+
+    # Direct match on ID
+    if workspace in workspace_map:
+        return workspace
+
+    # Match on name (case-insensitive)
+    for ws_id, ws_name in workspace_map.items():
+        if ws_name and workspace.lower() == str(ws_name).lower():
+            return ws_id
+
+    click.echo(f"✗ Workspace '{workspace}' not found. Provide a valid name or ID.", err=True)
+    sys.exit(ExitCodes.INVALID_INPUT)
+
+
+def _serialize_results(results: List[ProvisioningResult]) -> List[Dict[str, Any]]:
+    """Convert provisioning results into serializable dictionaries."""
+    serialized: List[Dict[str, Any]] = []
+    for res in results:
+        action_value = (
+            res.action.value if isinstance(res.action, ProvisioningAction) else str(res.action)
+        )
+        serialized.append(
+            {
+                "id_reference": res.id_reference,
+                "resource_type": res.resource_type,
+                "resource_name": res.resource_name,
+                "action": action_value,
+                "server_id": res.server_id,
+                "error": res.error,
+            }
+        )
+    return serialized
+
+
+def _result_row_formatter(item: Dict[str, Any]) -> List[str]:
+    """Formatter for table rows in provisioning output."""
+    return [
+        item.get("resource_name", ""),
+        item.get("resource_type", ""),
+        item.get("action", ""),
+        item.get("server_id", "") or "-",
+        item.get("error", "") or "",
+    ]
+
+
+def _example_row_formatter(item: Dict[str, Any]) -> List[str]:
+    """Formatter for table rows in example list output."""
+    tags = item.get("tags") or []
+    setup = item.get("estimated_setup_time_minutes", 0)
+    return [
+        item.get("name", ""),
+        item.get("title", ""),
+        ", ".join(tags),
+        str(setup),
+        item.get("author", ""),
+    ]
+
+
+def _output_results(results: List[Dict[str, Any]], format_output: str) -> None:
+    """Render provisioning results in the requested format."""
+    UniversalResponseHandler.handle_list_response(
+        resp=FilteredResponse({"resources": results}),
+        data_key="resources",
+        item_name="resource",
+        format_output=format_output,
+        formatter_func=_result_row_formatter,
+        headers=["Name", "Type", "Action", "Server ID", "Error"],
+        column_widths=[45, 12, 10, 38, 30],
+        empty_message="No resources processed.",
+        enable_pagination=False,
+    )
+
+
+def _write_audit_log(
+    results: List[Dict[str, Any]], audit_log: Optional[str], quiet: bool = False
+) -> None:
+    """Persist results to an audit log file if requested."""
+    if not audit_log:
+        return
+    save_json_file(results, audit_log)
+    if not quiet:
+        click.echo(f"Audit log saved to {audit_log}", err=True)
+
+
+def register_example_commands(cli: Any) -> None:
+    """Register example command group.
+
+    Args:
+        cli: Click CLI group to register commands on.
+    """
+
+    @cli.group()
+    def example() -> None:
+        """Manage example resource configurations.
+
+        Examples help you quickly set up demo systems for training,
+        testing, or evaluation. Each example includes systems, assets,
+        DUTs, templates, and other resources needed for a complete workflow.
+
+        Workspace: Uses default workspace unless --workspace specified.
+        """
+        pass
+
+    @example.command(name="list")
+    @click.option(
+        "--format",
+        "-f",
+        type=click.Choice(["table", "json"]),
+        default="table",
+        help="Output format",
+    )
+    def list_examples(format: str) -> None:
+        """List available example configurations.
+
+        Shows all examples with descriptions, tags, and estimated setup time.
+        """
+        try:
+            loader = ExampleLoader()
+            examples = loader.list_examples()
+
+            if not examples:
+                if format == "json":
+                    click.echo("[]")
+                else:
+                    click.echo("No examples available.", err=True)
+                return
+
+            if format == "json":
+                # JSON: show all at once
+                click.echo(json.dumps(examples, indent=2))
+            else:
+                UniversalResponseHandler.handle_list_response(
+                    resp=FilteredResponse({"examples": examples}),
+                    data_key="examples",
+                    item_name="example",
+                    format_output=format,
+                    formatter_func=_example_row_formatter,
+                    headers=["Name", "Title", "Tags", "Setup (min)", "Author"],
+                    column_widths=[35, 28, 24, 11, 18],
+                    enable_pagination=False,  # Unlikely to have > 25 examples
+                )
+
+        except Exception as exc:
+            handle_api_error(exc)
+
+    @example.command(name="info")
+    @click.argument("example_name")
+    @click.option(
+        "--format",
+        "-f",
+        type=click.Choice(["table", "json"]),
+        default="table",
+        help="Output format",
+    )
+    def info_example(example_name: str, format: str) -> None:
+        """Show detailed information about an example.
+
+        Displays full config including resources, dependencies, and
+        estimated setup time.
+
+        Example:
+            slcli example info demo-test-plans
+        """
+        try:
+            loader = ExampleLoader()
+            config = loader.load_config(example_name)
+
+            if format == "json":
+                # JSON: dump full config
+                click.echo(json.dumps(config, indent=2))
+            else:
+                # Table format: show summary and resources
+                click.echo(f"\n{'='*70}")
+                click.echo(f"Example: {config['title']}")
+                click.echo(f"{'='*70}")
+                click.echo(f"Name:        {config.get('name', 'N/A')}")
+                click.echo(f"Author:      {config.get('author', 'N/A')}")
+                click.echo(f"Setup Time:  {config.get('estimated_setup_time_minutes', 0)} minutes")
+                click.echo(f"Tags:        {', '.join(config.get('tags', []))}")
+                click.echo()
+                click.echo(f"Description:\n{config.get('description', 'N/A')}")
+                click.echo()
+
+                # Show resources
+                resources = config.get("resources", [])
+                click.echo(f"\nResources ({len(resources)} total):")
+                click.echo("-" * 70)
+
+                for resource in resources:
+                    res_type = resource.get("type", "unknown")
+                    res_name = resource.get("name", "N/A")
+                    res_ref = resource.get("id_reference", "N/A")
+                    click.echo(f"  {res_type:15} {res_name:30} (${{{res_ref}}})")
+
+                click.echo(f"{'='*70}\n")
+
+        except FileNotFoundError as e:
+            click.echo(f"✗ Error: {e}", err=True)
+            sys.exit(ExitCodes.NOT_FOUND)
+        except ValueError as e:
+            click.echo(f"✗ Error: {e}", err=True)
+            sys.exit(ExitCodes.INVALID_INPUT)
+        except Exception as exc:
+            handle_api_error(exc)
+
+    @example.command(name="install")
+    @click.argument("example_name")
+    @click.option("--workspace", "-w", required=True, help="Workspace name or ID for resources")
+    @click.option(
+        "--format",
+        "-f",
+        type=click.Choice(["table", "json"]),
+        default="table",
+        help="Output format for provisioning results",
+    )
+    @click.option(
+        "--dry-run",
+        is_flag=True,
+        help="Validate and preview resource creation without calling APIs.",
+    )
+    @click.option(
+        "--audit-log",
+        "-a",
+        type=click.Path(dir_okay=False, writable=True, resolve_path=True),
+        help="Path to write provisioning results as JSON for auditing.",
+    )
+    def install_example(
+        example_name: str,
+        workspace: Optional[str],
+        format: str,
+        dry_run: bool,
+        audit_log: Optional[str],
+    ) -> None:
+        """Provision all resources defined by an example configuration."""
+        try:
+            loader = ExampleLoader()
+            config = loader.load_config(example_name)
+
+            workspace_id = _resolve_workspace_id(get_effective_workspace(workspace))
+            provisioner = ExampleProvisioner(
+                workspace_id=workspace_id,
+                example_name=example_name,
+                dry_run=dry_run,
+            )
+
+            results, err = provisioner.provision(config)
+            if err:
+                handle_api_error(err)
+
+            serialized = _serialize_results(results)
+            _write_audit_log(serialized, audit_log, quiet=format == "json")
+            _output_results(serialized, format)
+
+            failed = any(r.get("action") == ProvisioningAction.FAILED.value for r in serialized)
+            if failed:
+                click.echo("✗ One or more resources failed to provision.", err=True)
+                sys.exit(ExitCodes.GENERAL_ERROR)
+
+            if format == "json":
+                return
+
+            created_count = sum(
+                1 for r in serialized if r.get("action") == ProvisioningAction.CREATED.value
+            )
+            skipped_count = sum(
+                1 for r in serialized if r.get("action") == ProvisioningAction.SKIPPED.value
+            )
+
+            summary_message = "Dry-run completed" if dry_run else "Example install completed"
+            format_success(
+                summary_message,
+                {
+                    "example": example_name,
+                    "workspace": workspace_id or "default",
+                    "created": created_count,
+                    "skipped": skipped_count,
+                },
+            )
+
+        except FileNotFoundError as e:
+            click.echo(f"✗ Error: {e}", err=True)
+            sys.exit(ExitCodes.NOT_FOUND)
+        except ValueError as e:
+            click.echo(f"✗ Error: {e}", err=True)
+            sys.exit(ExitCodes.INVALID_INPUT)
+        except Exception as exc:
+            handle_api_error(exc)
+
+    @example.command(name="delete")
+    @click.argument("example_name")
+    @click.option("--workspace", "-w", required=True, help="Workspace name or ID for resources")
+    @click.option(
+        "--format",
+        "-f",
+        type=click.Choice(["table", "json"]),
+        default="table",
+        help="Output format for deletion results",
+    )
+    @click.option(
+        "--dry-run",
+        is_flag=True,
+        help="Preview deletions without calling APIs.",
+    )
+    @click.option(
+        "--audit-log",
+        "-a",
+        type=click.Path(dir_okay=False, writable=True, resolve_path=True),
+        help="Path to write deletion results as JSON for auditing.",
+    )
+    def delete_example(
+        example_name: str,
+        workspace: Optional[str],
+        format: str,
+        dry_run: bool,
+        audit_log: Optional[str],
+    ) -> None:
+        """Delete resources for an example configuration in reverse order."""
+        from .utils import check_readonly_mode
+
+        check_readonly_mode("delete an example")
+
+        try:
+            loader = ExampleLoader()
+            config = loader.load_config(example_name)
+
+            workspace_id = _resolve_workspace_id(get_effective_workspace(workspace))
+            provisioner = ExampleProvisioner(
+                workspace_id=workspace_id,
+                example_name=example_name,
+                dry_run=dry_run,
+            )
+
+            results, err = provisioner.delete(config)
+            if err:
+                handle_api_error(err)
+
+            serialized = _serialize_results(results)
+            _write_audit_log(serialized, audit_log, quiet=format == "json")
+            _output_results(serialized, format)
+
+            failed = any(r.get("action") == ProvisioningAction.FAILED.value for r in serialized)
+            if failed:
+                click.echo("✗ One or more resources failed to delete.", err=True)
+                sys.exit(ExitCodes.GENERAL_ERROR)
+
+            if format == "json":
+                return
+
+            deleted_count = sum(
+                1 for r in serialized if r.get("action") == ProvisioningAction.DELETED.value
+            )
+            skipped_count = sum(
+                1 for r in serialized if r.get("action") == ProvisioningAction.SKIPPED.value
+            )
+
+            summary_message = "Dry-run completed" if dry_run else "Example delete completed"
+            format_success(
+                summary_message,
+                {
+                    "example": example_name,
+                    "workspace": workspace_id or "default",
+                    "deleted": deleted_count,
+                    "skipped": skipped_count,
+                },
+            )
+
+        except FileNotFoundError as e:
+            click.echo(f"✗ Error: {e}", err=True)
+            sys.exit(ExitCodes.NOT_FOUND)
+        except ValueError as e:
+            click.echo(f"✗ Error: {e}", err=True)
+            sys.exit(ExitCodes.INVALID_INPUT)
+        except Exception as exc:
+            handle_api_error(exc)

slcli/example_loader.py

@@ -0,0 +1,274 @@
+"""Load and validate example configurations."""
+
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import yaml  # type: ignore
+
+
+class ExampleLoader:
+    """Load and validate example configurations from local examples/ directory."""
+
+    # Supported schema versions
+    SUPPORTED_SCHEMA_VERSIONS = {"1.0"}
+
+    # Required fields in config
+    REQUIRED_FIELDS = {"format_version", "name", "title", "resources"}
+
+    # Required resource fields
+    REQUIRED_RESOURCE_FIELDS = {"type", "name", "properties", "id_reference"}
+
+    # Supported resource types
+    SUPPORTED_RESOURCE_TYPES = {
+        "location",
+        "product",
+        "system",
+        "asset",
+        "dut",
+        "testtemplate",
+        "workflow",
+        "work_item",
+        "work_order",
+        "test_result",
+        "data_table",
+        "file",
+        "notebook",
+    }
+
+    def __init__(self, examples_dir: Optional[Path] = None) -> None:
+        """Initialize loader with path to examples directory.
+
+        Args:
+            examples_dir: Path to examples directory. Defaults to slcli/examples/.
+        """
+        self.examples_dir = examples_dir or Path(__file__).parent / "examples"
+        self._schema: Optional[Dict[str, Any]] = None
+
+    def list_examples(self) -> List[Dict[str, Any]]:
+        """List all available examples with metadata.
+
+        Returns:
+            List of dicts with keys: name, title, description, tags,
+            estimated_setup_time_minutes, author.
+        """
+        examples = []
+        for example_dir in sorted(self.examples_dir.iterdir()):
+            # Skip special directories and non-directories
+            if not example_dir.is_dir() or example_dir.name.startswith("_"):
+                continue
+
+            config_path = example_dir / "config.yaml"
+            if not config_path.exists():
+                continue
+
+            try:
+                config = self.load_config(example_dir.name)
+                examples.append(
+                    {
+                        "name": config["name"],
+                        "title": config["title"],
+                        "description": config.get("description", ""),
+                        "tags": config.get("tags", []),
+                        "estimated_setup_time_minutes": config.get(
+                            "estimated_setup_time_minutes", 0
+                        ),
+                        "author": config.get("author", "Unknown"),
+                    }
+                )
+            except (FileNotFoundError, ValueError):
+                # Skip invalid examples
+                continue
+
+        return examples
+
+    def load_config(self, example_name: str) -> Dict[str, Any]:
+        """Load and validate example configuration.
+
+        Args:
+            example_name: Name of example (directory name).
+
+        Returns:
+            Validated config dictionary.
+
+        Raises:
+            FileNotFoundError: If example config not found.
+            ValueError: If config fails validation.
+        """
+        config_path = self.examples_dir / example_name / "config.yaml"
+        if not config_path.exists():
+            raise FileNotFoundError(
+                f"Example '{example_name}' not found. " f"Config path: {config_path}"
+            )
+
+        # Load YAML
+        try:
+            with open(config_path, "r") as f:
+                config = yaml.safe_load(f)
+        except yaml.YAMLError as e:
+            raise ValueError(f"Invalid YAML in {config_path}: {e}")
+
+        if not isinstance(config, dict):
+            raise ValueError(f"Config must be a dictionary, got {type(config)}")
+
+        # Validate schema
+        errors = self.validate_config(config)
+        if errors:
+            msg = f"Config validation failed for '{example_name}':\n"
+            msg += "\n".join(f"  - {e}" for e in errors)
+            raise ValueError(msg)
+
+        # Validate references
+        ref_errors = self._validate_references(config)
+        if ref_errors:
+            msg = f"Reference validation failed for '{example_name}':\n"
+            msg += "\n".join(f"  - {e}" for e in ref_errors)
+            raise ValueError(msg)
+
+        return config
+
+    def validate_config(self, config: Dict[str, Any]) -> List[str]:
+        """Validate config against basic schema requirements.
+
+        Args:
+            config: Config dictionary to validate.
+
+        Returns:
+            List of validation error messages (empty if valid).
+        """
+        errors = []
+
+        # Check all required top-level fields are present
+
+        missing_fields = self.REQUIRED_FIELDS - set(config.keys())
+        if missing_fields:
+            errors.append(f"Missing required fields: {', '.join(sorted(missing_fields))}")
+
+        # Check format_version is supported
+        version = config.get("format_version")
+        if version and version not in self.SUPPORTED_SCHEMA_VERSIONS:
+            errors.append(
+                f"Unsupported format_version '{version}'. "
+                f"Supported: {self.SUPPORTED_SCHEMA_VERSIONS}"
+            )
+
+        # Validate resources
+        resources = config.get("resources", [])
+        if not isinstance(resources, list):
+            errors.append("resources must be a list")
+        else:
+            for idx, resource in enumerate(resources):
+                if not isinstance(resource, dict):
+                    errors.append(f"Resource {idx}: must be a dictionary")
+                    continue
+
+                # Check required resource fields
+                missing = self.REQUIRED_RESOURCE_FIELDS - set(resource.keys())
+                if missing:
+                    errors.append(f"Resource {idx}: missing fields: {', '.join(sorted(missing))}")
+
+                # Check resource type is supported
+                res_type = resource.get("type")
+                if res_type and res_type not in self.SUPPORTED_RESOURCE_TYPES:
+                    errors.append(
+                        f"Resource {idx}: unsupported type '{res_type}'. "
+                        f"Supported: {', '.join(sorted(self.SUPPORTED_RESOURCE_TYPES))}"
+                    )
+
+                # Validate id_reference format (should be valid identifier)
+                id_ref = resource.get("id_reference", "")
+                if id_ref and not self._is_valid_identifier(id_ref):
+                    errors.append(
+                        f"Resource {idx}: invalid id_reference '{id_ref}'. "
+                        f"Must start with letter or underscore, contain only "
+                        f"alphanumeric and underscores."
+                    )
+
+        return errors
+
+    def _is_valid_identifier(self, name: str) -> bool:
+        """Check if name is a valid Python identifier."""
+        if not name:
+            return False
+        if not (name[0].isalpha() or name[0] == "_"):
+            return False
+        return all(c.isalnum() or c == "_" for c in name)
+
+    def _validate_references(self, config: Dict[str, Any]) -> List[str]:
+        """Validate that all ${ref} references are defined.
+
+        Args:
+            config: Config dictionary.
+
+        Returns:
+            List of reference error messages.
+        """
+        errors = []
+
+        # Collect all defined id_references
+        defined_refs = set()
+        resources = config.get("resources", [])
+        if not isinstance(resources, list):
+            return ["resources must be a list"]
+
+        for resource in resources:
+            if isinstance(resource, dict):
+                ref = resource.get("id_reference")
+                if ref:
+                    defined_refs.add(ref)
+
+        # Check all ${ref} references are defined
+        for resource in resources:
+            if not isinstance(resource, dict):
+                continue
+
+            # Check in resource properties
+            props = resource.get("properties", {})
+            if isinstance(props, dict):
+                ref_errors = self._collect_undefined_refs(props, defined_refs)
+                errors.extend(ref_errors)
+
+        return errors
+
+    def _collect_undefined_refs(self, obj: Any, defined_refs: set) -> List[str]:
+        """Recursively collect undefined references from an object.
+
+        Args:
+            obj: Object to scan (dict, list, string, etc).
+            defined_refs: Set of defined id_references.
+
+        Returns:
+            List of error messages for undefined references.
+        """
+        errors = []
+
+        if isinstance(obj, dict):
+            for value in obj.values():
+                errors.extend(self._collect_undefined_refs(value, defined_refs))
+        elif isinstance(obj, list):
+            for item in obj:
+                errors.extend(self._collect_undefined_refs(item, defined_refs))
+        elif isinstance(obj, str):
+            # Check for ${ref} pattern
+            if obj.startswith("${") and obj.endswith("}"):
+                ref = obj[2:-1]
+                if ref not in defined_refs:
+                    errors.append(
+                        f"Undefined reference: {obj}. "
+                        f"Defined references: {sorted(defined_refs)}"
+                    )
+
+        return errors
+
+    def get_resource_order(self, config: Dict[str, Any]) -> List[Dict[str, Any]]:
+        """Get resources in provisioning order (as listed in config).
+
+        Args:
+            config: Config dictionary.
+
+        Returns:
+            List of resource definitions.
+        """
+        resources = config.get("resources", [])
+        if not isinstance(resources, list):
+            return []
+        return [r for r in resources if isinstance(r, dict)]