datex-studio-cli 0.4.5__tar.gz → 0.4.7__tar.gz

{datex_studio_cli-0.4.5 → datex_studio_cli-0.4.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datex-studio-cli
-Version: 0.4.5
+Version: 0.4.7
 Summary: CLI for Datex Studio low-code platform, designed for LLM-based AI agents
 Project-URL: Homepage, https://github.com/datex/datex-studio-cli
 Project-URL: Documentation, https://github.com/datex/datex-studio-cli

{datex_studio_cli-0.4.5 → datex_studio_cli-0.4.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "datex-studio-cli"
-version = "0.4.5"
+version = "0.4.7"
 description = "CLI for Datex Studio low-code platform, designed for LLM-based AI agents"
 readme = "README.md"
 license = "MIT"

{datex_studio_cli-0.4.5 → datex_studio_cli-0.4.7}/src/dxs/__init__.py

@@ -1,4 +1,4 @@
 """Datex Studio CLI - Command-line interface for Datex Studio platform."""
 
-__version__ = "0.4.5"
+__version__ = "0.4.7"
 __app_name__ = "dxs"

{datex_studio_cli-0.4.5 → datex_studio_cli-0.4.7}/src/dxs/cli.py

@@ -390,8 +390,10 @@ def handle_errors(f: F) -> F:
             _record_error_silently(e)
             dxs_ctx.output_error(e)
             sys.exit(1)
-        except click.ClickException:
-            # Let Click handle its own exceptions
+        except (click.ClickException, click.Abort, click.exceptions.Exit):
+            # Let Click handle its own exceptions and control-flow signals
+            # (Abort from confirm(abort=True), Exit from ctx.exit) — these are
+            # not errors and must not be rendered as error envelopes.
             raise
         except Exception as e:
             _record_error_silently(e)

datex_studio_cli-0.4.7/src/dxs/commands/configuration.py

@@ -0,0 +1,533 @@
+"""Generic platform configuration commands: dxs configuration [get|create|update|upsert|validate|list|delete|contexts|types].
+
+Canonical CRUD surface for any of ConfigurationEndpoints.KNOWN_TYPES
+(hub, grid, form, editor, flow, etc.). Provides the missing primitive
+that previously forced users to hand-craft `dxs api` calls and
+reverse-engineer endpoint paths.
+
+Verb vocabulary:
+- `create` — POST, fails if exists. Requires the caller to know the
+  config does not already exist on the branch.
+- `update` — PUT, requires the numeric ID. Requires the caller to know
+  the config exists.
+- `upsert` — orchestrated create-or-update by referenceName, handles
+  the Datex Studio source-control lock protocol on the caller's behalf.
+  This is the right verb when the caller does not know which case
+  applies.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import click
+
+from dxs.cli import DxsContext, handle_errors, pass_context
+from dxs.core.api.client import ApiClient
+from dxs.core.api.endpoints import ConfigurationEndpoints
+from dxs.core.auth import require_auth
+from dxs.core.designer.parsers import is_valid_js_identifier
+from dxs.utils.click_options import resolve_branch
+from dxs.utils.errors import ValidationError
+from dxs.utils.resolvers import resolve_config_by_reference, upsert_config
+from dxs.utils.responses import list_response, single
+from dxs.utils.restricted import restrict_in_restricted_mode
+
+
+def _validate_type(config_type: str) -> str:
+    normalized = ConfigurationEndpoints.normalize_type(config_type)
+    if normalized not in ConfigurationEndpoints.KNOWN_TYPES:
+        known = ", ".join(sorted(ConfigurationEndpoints.KNOWN_TYPES))
+        raise ValidationError(
+            message=f"Unknown configuration type: {config_type!r}",
+            code="DXS-CFG-001",
+            suggestions=[f"Use one of: {known}"],
+        )
+    return normalized
+
+
+def _load_body(data_file: Path) -> Any:
+    try:
+        return json.loads(data_file.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as e:
+        raise ValidationError(
+            message=f"Invalid JSON in {data_file}: {e}",
+            code="DXS-CFG-002",
+            suggestions=[f"Validate the file with: python -m json.tool {data_file}"],
+        ) from e
+
+
+@click.group("configuration")
+def configuration() -> None:
+    """Manage platform configuration objects (hub, grid, form, editor, flow, etc.).
+
+    These are the deployable artifacts on a Datex Studio branch — distinct from
+    `dxs config`/`dxs settings`, which manage local CLI settings.
+
+    The CRUD surface is uniform across every type in `dxs configuration types`.
+    Pair `get` (with --output-file) and `update` (with --data-file) to fetch a
+    config, edit it locally, and push it back without shell-escaping a large
+    JSON payload. Use `create` for new configs, `upsert` when you do not know
+    whether the config already exists, and `delete` to remove them; `validate`
+    and `contexts` run the platform's authoring-time checks.
+
+    \b
+    Examples:
+        dxs configuration types
+        dxs configuration list hub -b 64
+        dxs configuration get hub 8642750 -b 64 --output-file envelope.json
+        jq .json envelope.json > body.json   # extract inner body for update
+        # edit body.json
+        dxs configuration update hub 8642750 -b 64 --data-file body.json
+        dxs configuration create grid -b 64 --data-file new_grid.json
+        dxs configuration upsert datasource -b 64 --data-file ds.json
+        dxs configuration validate grid -b 64 --data-file new_grid.json
+        dxs configuration delete grid 8642750 -b 64 --yes
+    """
+
+
+@configuration.command("types")
+@pass_context
+def configuration_types(ctx: DxsContext) -> None:
+    """List the known platform configuration type names accepted by these commands."""
+    types = sorted(ConfigurationEndpoints.KNOWN_TYPES)
+    ctx.output(
+        single(item={"types": types, "count": len(types)}, semantic_key="configuration_types")
+    )
+
+
+@configuration.command("get")
+@click.argument("config_type")
+@click.argument("config_ref")
+@click.option("--branch", "-b", type=int, default=None, help="Branch ID (falls back to global -b)")
+@click.option(
+    "--output-file",
+    "-O",
+    "output_file",
+    type=click.Path(dir_okay=False, writable=True, path_type=Path),
+    default=None,
+    help=(
+        "Write the full server envelope JSON to a file. To round-trip through "
+        "`update -D`, first extract the inner body (e.g., `jq .json envelope.json > body.json`)."
+    ),
+)
+@pass_context
+@require_auth
+@handle_errors
+def configuration_get(
+    ctx: DxsContext,
+    config_type: str,
+    config_ref: str,
+    branch: int | None,
+    output_file: Path | None,
+) -> None:
+    """Fetch a platform configuration by type and ID or reference name.
+
+    \b
+    Arguments:
+        CONFIG_TYPE  Configuration type (e.g., hub, grid, form, editor, flow)
+        CONFIG_REF   Numeric configuration ID, or the config's reference name.
+                     Reference names are valid JS identifiers (never all-digits),
+                     so an all-digit value is always treated as an ID.
+
+    \b
+    Examples:
+        dxs configuration get hub 8642750 -b 64
+        dxs configuration get hub hub_home -b 64
+        dxs configuration get hub hub_home -b 64 -O hub.json
+    """
+    config_type = _validate_type(config_type)
+    branch_id = resolve_branch(ctx, branch, "DXS-CFG-010")
+
+    api_client = ApiClient()
+    if config_ref.isdigit():
+        path = ConfigurationEndpoints.get_content(branch_id, config_type, int(config_ref))
+        body = api_client.get(path)
+    else:
+        body = resolve_config_by_reference(api_client, branch_id, config_type, config_ref)
+
+    if output_file is not None:
+        output_file.write_text(
+            json.dumps(body, indent=2, ensure_ascii=False),
+            encoding="utf-8",
+        )
+        ctx.log(f"Wrote {config_type} configuration {config_ref} to {output_file}")
+        return
+
+    ctx.output(single(item=body, semantic_key="configuration"))
+
+
+@configuration.command("update")
+@click.argument("config_type")
+@click.argument("config_ref")
+@click.option(
+    "--data-file",
+    "-D",
+    "data_file",
+    required=True,
+    type=click.Path(exists=True, dir_okay=False, readable=True, path_type=Path),
+    help="JSON file containing the full configuration body to PUT.",
+)
+@click.option("--branch", "-b", type=int, default=None, help="Branch ID (falls back to global -b)")
+@pass_context
+@require_auth
+@handle_errors
+@restrict_in_restricted_mode("modifies platform configurations")
+def configuration_update(
+    ctx: DxsContext,
+    config_type: str,
+    config_ref: str,
+    data_file: Path,
+    branch: int | None,
+) -> None:
+    """Update a platform configuration via PUT with a body read from a file.
+
+    The body is read from disk (no shell escaping), so payloads with embedded
+    \\r\\n sequences, nested quotes, or large flow code blocks round-trip
+    cleanly. The target may be a numeric ID or a reference name (an all-digit
+    value is always treated as an ID). For create-or-update by referenceName
+    with source-control lock handling, prefer `upsert`.
+
+    \b
+    Examples:
+        dxs configuration update hub 8642750 -b 64 -D hub.json
+        dxs configuration update hub hub_home -b 64 -D hub.json
+        dxs configuration update flow 12345 -b 64 -D flow_body.json
+    """
+    config_type = _validate_type(config_type)
+    branch_id = resolve_branch(ctx, branch, "DXS-CFG-010")
+
+    body = _load_body(data_file)
+    api_client = ApiClient()
+    if config_ref.isdigit():
+        config_id = int(config_ref)
+    else:
+        resolved = resolve_config_by_reference(api_client, branch_id, config_type, config_ref)
+        config_id = resolved["id"]
+    path = ConfigurationEndpoints.update(branch_id, config_type, config_id)
+    response = api_client.put(path, data=body)
+
+    ctx.output(
+        single(
+            item={
+                "id": config_id,
+                "type": config_type,
+                "branch_id": branch_id,
+                "source_file": str(data_file),
+                "response": response,
+            },
+            semantic_key="configuration_update",
+        )
+    )
+
+
+@configuration.command("create")
+@click.argument("config_type")
+@click.option(
+    "--data-file",
+    "-D",
+    "data_file",
+    required=True,
+    type=click.Path(exists=True, dir_okay=False, readable=True, path_type=Path),
+    help="JSON file containing the full configuration body to POST.",
+)
+@click.option("--branch", "-b", type=int, default=None, help="Branch ID (falls back to global -b)")
+@pass_context
+@require_auth
+@restrict_in_restricted_mode("creates platform configurations")
+def configuration_create(
+    ctx: DxsContext,
+    config_type: str,
+    data_file: Path,
+    branch: int | None,
+) -> None:
+    """Create a new platform configuration via POST with a body read from a file.
+
+    The body is read from disk (no shell escaping), so payloads with embedded
+    \\r\\n sequences, nested quotes, or large flow code blocks round-trip cleanly.
+
+    \b
+    Examples:
+        dxs configuration create grid -b 64 -D new_grid.json
+        dxs configuration create flow -b 64 -D fn_body.json
+    """
+    config_type = _validate_type(config_type)
+    branch_id = resolve_branch(ctx, branch, "DXS-CFG-010")
+
+    body = _load_body(data_file)
+    api_client = ApiClient()
+    path = ConfigurationEndpoints.create(branch_id, config_type)
+    response = api_client.post(path, data=body)
+
+    ctx.output(
+        single(
+            item={
+                "type": config_type,
+                "branch_id": branch_id,
+                "source_file": str(data_file),
+                "response": response,
+            },
+            semantic_key="configuration_create",
+        )
+    )
+
+
+@configuration.command("upsert")
+@click.argument("config_type")
+@click.option(
+    "--data-file",
+    "-D",
+    "data_file",
+    required=True,
+    type=click.Path(exists=True, dir_okay=False, readable=True, path_type=Path),
+    help="JSON file containing the full configuration body.",
+)
+@click.option("--branch", "-b", type=int, default=None, help="Branch ID (falls back to global -b)")
+@pass_context
+@require_auth
+@restrict_in_restricted_mode("creates or updates platform configurations")
+@handle_errors
+def configuration_upsert(
+    ctx: DxsContext,
+    config_type: str,
+    data_file: Path,
+    branch: int | None,
+) -> None:
+    """Create or update a platform configuration (orchestrated upsert).
+
+    Reads the configuration body from a JSON file, looks up the existing
+    config on the branch by referenceName, then either POSTs (create) or
+    locks+PUTs (update) atomically. Handles the Datex Studio source-control
+    lock protocol on the user's behalf — inherited configs are locked before
+    PUT, and locks are released best-effort if the PUT fails.
+
+    \b
+    Examples:
+        dxs configuration upsert datasource -b 64 -D ds_orders.json
+        dxs configuration upsert flow      -b 64 -D fn_body.json
+    """
+    config_type = _validate_type(config_type)
+    branch_id = resolve_branch(ctx, branch, "DXS-CFG-010")
+
+    body = _load_body(data_file)
+
+    if not isinstance(body, dict):
+        raise ValidationError(
+            message=f"{data_file} must contain a JSON object at the top level.",
+            code="DXS-CFG-003",
+            suggestions=[
+                "Use 'dxs datasource generate' or 'dxs function generate' to produce a valid body."
+            ],
+        )
+
+    ref_name = body.get("referenceName")
+    if not ref_name or not is_valid_js_identifier(ref_name):
+        raise ValidationError(
+            message=(
+                f"{data_file} must contain a 'referenceName' that is a valid JavaScript identifier."
+            ),
+            code="DXS-CFG-004",
+            suggestions=[
+                "Use 'dxs datasource generate' or 'dxs function generate' to produce a valid file.",
+            ],
+        )
+
+    api_client = ApiClient()
+    response, action = upsert_config(api_client, branch_id, config_type, ref_name, body)
+
+    ctx.output(
+        single(
+            item={
+                "type": config_type,
+                "branch_id": branch_id,
+                "source_file": str(data_file),
+                "action": action,
+                "response": response,
+            },
+            semantic_key="configuration_upsert",
+        )
+    )
+
+
+@configuration.command("validate")
+@click.argument("config_type")
+@click.option(
+    "--data-file",
+    "-D",
+    "data_file",
+    required=True,
+    type=click.Path(exists=True, dir_okay=False, readable=True, path_type=Path),
+    help="JSON file containing the configuration body to validate.",
+)
+@click.option("--branch", "-b", type=int, default=None, help="Branch ID (falls back to global -b)")
+@pass_context
+@require_auth
+def configuration_validate(
+    ctx: DxsContext,
+    config_type: str,
+    data_file: Path,
+    branch: int | None,
+) -> None:
+    """Validate a platform configuration body against a branch.
+
+    Returns either {status: "valid"} or a list of validation_errors.
+
+    \b
+    Examples:
+        dxs configuration validate grid -b 64 -D grid.json
+        dxs configuration validate flow -b 64 -D fn_body.json
+    """
+    config_type = _validate_type(config_type)
+    branch_id = resolve_branch(ctx, branch, "DXS-CFG-010")
+
+    body = _load_body(data_file)
+    api_client = ApiClient()
+    path = ConfigurationEndpoints.validate_config(branch_id, config_type)
+    response = api_client.post(path, data=body)
+
+    errors = response if isinstance(response, list) else []
+    if not errors:
+        ctx.output(
+            single(
+                item={"status": "valid", "message": "No validation errors"},
+                semantic_key="validation_result",
+            )
+        )
+    else:
+        formatted = [
+            {"message": e.get("message", str(e)) if isinstance(e, dict) else str(e)}
+            for e in errors
+        ]
+        ctx.output(list_response(items=formatted, semantic_key="validation_errors"))
+
+
+@configuration.command("contexts")
+@click.argument("config_type")
+@click.option(
+    "--data-file",
+    "-D",
+    "data_file",
+    required=True,
+    type=click.Path(exists=True, dir_okay=False, readable=True, path_type=Path),
+    help="JSON file containing the configuration body whose designer contexts you want.",
+)
+@click.option("--branch", "-b", type=int, default=None, help="Branch ID (falls back to global -b)")
+@pass_context
+@require_auth
+def configuration_contexts(
+    ctx: DxsContext,
+    config_type: str,
+    data_file: Path,
+    branch: int | None,
+) -> None:
+    """Get designer contexts (Monaco-editor type defs) for a configuration body.
+
+    Returns the same shape the platform's Monaco editor uses for IntelliSense
+    on flow code, expressions, and bindings.
+
+    \b
+    Examples:
+        dxs configuration contexts flow -b 64 -D fn.json
+        dxs configuration contexts datasource -b 64 -D ds.json
+    """
+    config_type = _validate_type(config_type)
+    branch_id = resolve_branch(ctx, branch, "DXS-CFG-010")
+
+    body = _load_body(data_file)
+    api_client = ApiClient()
+    path = ConfigurationEndpoints.contexts(branch_id, config_type)
+    response = api_client.post(path, data=body)
+
+    ctx.output(single(item=response or {}, semantic_key="configuration_contexts"))
+
+
+@configuration.command("list")
+@click.argument("config_type")
+@click.option("--branch", "-b", type=int, default=None, help="Branch ID (falls back to global -b)")
+@pass_context
+@require_auth
+def configuration_list(
+    ctx: DxsContext,
+    config_type: str,
+    branch: int | None,
+) -> None:
+    """List configurations of a given type on a branch.
+
+    \b
+    Examples:
+        dxs configuration list hub -b 64
+        dxs configuration list flow -b 64
+    """
+    config_type = _validate_type(config_type)
+    branch_id = resolve_branch(ctx, branch, "DXS-CFG-010")
+
+    api_client = ApiClient()
+    path = ConfigurationEndpoints.list_all(branch_id, config_type)
+    body = api_client.get(path)
+
+    ctx.output(single(item=body, semantic_key="configurations"))
+
+
+@configuration.command("delete")
+@click.argument("config_type")
+@click.argument("config_ref")
+@click.option("--branch", "-b", type=int, default=None, help="Branch ID (falls back to global -b)")
+@click.option("--yes", "-y", is_flag=True, help="Skip the confirmation prompt.")
+@pass_context
+@require_auth
+@handle_errors
+@restrict_in_restricted_mode("deletes platform configurations")
+def configuration_delete(
+    ctx: DxsContext,
+    config_type: str,
+    config_ref: str,
+    branch: int | None,
+    yes: bool,
+) -> None:
+    """Delete a platform configuration by type and ID or reference name.
+
+    \b
+    Arguments:
+        CONFIG_TYPE  Configuration type (e.g., hub, grid, form, editor, flow)
+        CONFIG_REF   Numeric configuration ID, or the config's reference name.
+                     An all-digit value is always treated as an ID.
+
+    \b
+    Examples:
+        dxs configuration delete grid 8642750 -b 64 --yes
+        dxs configuration delete grid my_grid -b 64 --yes
+    """
+    config_type = _validate_type(config_type)
+    branch_id = resolve_branch(ctx, branch, "DXS-CFG-010")
+
+    api_client = ApiClient()
+    if config_ref.isdigit():
+        config_id = int(config_ref)
+        label = str(config_id)
+    else:
+        resolved = resolve_config_by_reference(api_client, branch_id, config_type, config_ref)
+        config_id = resolved["id"]
+        label = f"{config_ref} (id {config_id})"
+
+    if not yes:
+        click.confirm(
+            f"Delete {config_type} configuration {label} on branch {branch_id}?",
+            abort=True,
+        )
+
+    path = ConfigurationEndpoints.delete(branch_id, config_type, config_id)
+    api_client.delete(path)
+
+    ctx.output(
+        single(
+            item={
+                "id": config_id,
+                "type": config_type,
+                "branch_id": branch_id,
+                "deleted": True,
+            },
+            semantic_key="configuration_delete",
+        )
+    )