datex-studio-cli 0.4.2__tar.gz → 0.4.3__tar.gz

{datex_studio_cli-0.4.2 → datex_studio_cli-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datex-studio-cli
-Version: 0.4.2
+Version: 0.4.3
 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.2 → datex_studio_cli-0.4.3}/pyproject.toml

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

{datex_studio_cli-0.4.2 → datex_studio_cli-0.4.3}/scripts/analyze_corpus.py

@@ -226,39 +226,39 @@ def main() -> None:
     for cat, cnt in category_counts.most_common():
         print(f"  {cat:30s} {cnt:4d}")
 
-    print(f"\n## Page Size Distribution")
+    print("\n## Page Size Distribution")
     for size, cnt in page_sizes.most_common():
         pct = cnt / total * 100
         print(f"  {size:30s} {cnt:4d}  ({pct:.0f}%)")
 
-    print(f"\n## Margin Distribution")
+    print("\n## Margin Distribution")
     for margin, cnt in margin_counter.most_common(15):
         pct = cnt / total * 100
         print(f"  {margin:55s} {cnt:4d}  ({pct:.0f}%)")
 
-    print(f"\n## Item Type Frequency")
+    print("\n## Item Type Frequency")
     for typ, cnt in item_type_counter.most_common():
         print(f"  {typ:25s} {cnt:5d}")
 
-    print(f"\n## Barcode Symbology Frequency")
+    print("\n## Barcode Symbology Frequency")
     for sym, cnt in barcode_symbology_counter.most_common():
         print(f"  {sym:25s} {cnt:4d}")
 
-    print(f"\n## Font Usage Frequency (top 20)")
+    print("\n## Font Usage Frequency (top 20)")
     for fnt, cnt in font_counter.most_common(20):
         print(f"  {fnt:30s} {cnt:5d}")
 
-    print(f"\n## Expression Pattern Frequency")
+    print("\n## Expression Pattern Frequency")
     for pat, cnt in expression_pattern_counter.most_common():
         print(f"  {pat:30s} {cnt:5d}")
 
-    print(f"\n## Dataset Count per Report")
+    print("\n## Dataset Count per Report")
     if dataset_counts:
         print(f"  Mean:   {mean(dataset_counts):.1f}")
         print(f"  Median: {median(dataset_counts):.1f}")
         print(f"  Range:  {min(dataset_counts)} - {max(dataset_counts)}")
 
-    print(f"\n## Element Count per Report by Category (body-level items)")
+    print("\n## Element Count per Report by Category (body-level items)")
     for cat in sorted(element_counts_by_category):
         counts = element_counts_by_category[cat]
         if counts:
@@ -269,7 +269,7 @@ def main() -> None:
                 f"n={len(counts)}"
             )
 
-    print(f"\n## Common Field Names by Category (top 10)")
+    print("\n## Common Field Names by Category (top 10)")
     for cat in sorted(field_names_by_category):
         top = field_names_by_category[cat].most_common(10)
         if top:
@@ -277,9 +277,9 @@ def main() -> None:
             for name, cnt in top:
                 print(f"    {name:30s} {cnt:4d}")
 
-    print(f"\n## PageHeader / PageFooter Usage")
-    print(f"  PageHeader: {page_header_count}/{total} ({page_header_count/total*100:.0f}%)")
-    print(f"  PageFooter: {page_footer_count}/{total} ({page_footer_count/total*100:.0f}%)")
+    print("\n## PageHeader / PageFooter Usage")
+    print(f"  PageHeader: {page_header_count}/{total} ({page_header_count / total * 100:.0f}%)")
+    print(f"  PageFooter: {page_footer_count}/{total} ({page_footer_count / total * 100:.0f}%)")
 
 
 if __name__ == "__main__":

{datex_studio_cli-0.4.2 → datex_studio_cli-0.4.3}/scripts/generate_rdlx_schema.py

@@ -241,9 +241,22 @@ def compare_schema(item_types: dict, items: list[dict]) -> dict:
         all_schema_props = schema_props | schema_style_props
         corpus_props = set(item_types[type_name]["properties"].keys())
         # Exclude common layout props that aren't type-specific
-        common_layout = {"Type", "Name", "Left", "Top", "Width", "Height", "ZIndex",
-                         "Visibility", "Style", "LayerName", "OverflowName", "Bookmark",
-                         "Label", "CustomProperties"}
+        common_layout = {
+            "Type",
+            "Name",
+            "Left",
+            "Top",
+            "Width",
+            "Height",
+            "ZIndex",
+            "Visibility",
+            "Style",
+            "LayerName",
+            "OverflowName",
+            "Bookmark",
+            "Label",
+            "CustomProperties",
+        }
         missing = sorted((corpus_props - all_schema_props) - common_layout)
         if missing:
             props_not_in_schema[type_name] = missing
@@ -296,13 +309,13 @@ def print_summary(schema: dict) -> None:
     # Common properties
     common = schema.get("common_properties", {})
     if common:
-        print(f"\n## Common Properties (shared across >=80% of item types)")
+        print("\n## Common Properties (shared across >=80% of item types)")
         for prop, info in sorted(common.items()):
             print(f"  {prop:25s}  {info['present_in']}")
 
     # Top properties per type (top 5 by count, excluding common)
     common_names = set(common.keys()) if common else set()
-    print(f"\n## Type-Specific Properties (top 10, excluding common)")
+    print("\n## Type-Specific Properties (top 10, excluding common)")
     for type_name, type_info in sorted(item_types.items(), key=lambda x: -x[1]["count"]):
         props = type_info["properties"]
         specific = [(k, v) for k, v in props.items() if k not in common_names]
@@ -322,41 +335,41 @@ def print_summary(schema: dict) -> None:
     # Comparison
     comp = schema.get("comparison", {})
     if comp and "error" not in comp:
-        print(f"\n## Schema Comparison (corpus vs schema.py)")
+        print("\n## Schema Comparison (corpus vs schema.py)")
 
         types_missing = comp.get("item_types_in_corpus_not_in_schema", [])
         if types_missing:
-            print(f"  Item types in corpus but NOT in schema.py:")
+            print("  Item types in corpus but NOT in schema.py:")
             for t in types_missing:
                 count = item_types.get(t, {}).get("count", "?")
                 print(f"    - {t} ({count} instances)")
 
         types_extra = comp.get("item_types_in_schema_not_in_corpus", [])
         if types_extra:
-            print(f"  Item types in schema.py but NOT in corpus:")
+            print("  Item types in schema.py but NOT in corpus:")
             for t in types_extra:
                 print(f"    - {t}")
 
         props_missing = comp.get("properties_in_corpus_not_in_schema", {})
         if props_missing:
-            print(f"  Properties in corpus but NOT in schema.py:")
+            print("  Properties in corpus but NOT in schema.py:")
             for type_name, props in sorted(props_missing.items()):
                 print(f"    {type_name}: {', '.join(props)}")
 
         sym_missing = comp.get("symbologies_in_corpus_not_in_schema", [])
         if sym_missing:
-            print(f"  Barcode symbologies in corpus but NOT in schema.py:")
+            print("  Barcode symbologies in corpus but NOT in schema.py:")
             for s in sym_missing:
                 print(f"    - {s}")
 
         sym_extra = comp.get("symbologies_in_schema_not_in_corpus", [])
         if sym_extra:
-            print(f"  Barcode symbologies in schema.py but NOT in corpus:")
+            print("  Barcode symbologies in schema.py but NOT in corpus:")
             for s in sym_extra:
                 print(f"    - {s}")
 
     if not comp or all(not v for v in comp.values() if isinstance(v, (list, dict))):
-        print(f"\n  Schema comparison: no gaps found!")
+        print("\n  Schema comparison: no gaps found!")
 
 
 # ── Main ─────────────────────────────────────────────────────────────────
@@ -364,12 +377,23 @@ def print_summary(schema: dict) -> None:
 
 def main() -> None:
     parser = argparse.ArgumentParser(description="Generate RDLX-JSON schema from report corpus")
-    parser.add_argument("directory", nargs="?", default="example-reports",
-                        help="Directory containing .rdlx-json files (default: example-reports/)")
-    parser.add_argument("-o", "--output", default="corpus-schema.json",
-                        help="Output JSON file path (default: corpus-schema.json)")
-    parser.add_argument("--summary-only", action="store_true",
-                        help="Print human-readable summary only, skip JSON output")
+    parser.add_argument(
+        "directory",
+        nargs="?",
+        default="example-reports",
+        help="Directory containing .rdlx-json files (default: example-reports/)",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        default="corpus-schema.json",
+        help="Output JSON file path (default: corpus-schema.json)",
+    )
+    parser.add_argument(
+        "--summary-only",
+        action="store_true",
+        help="Print human-readable summary only, skip JSON output",
+    )
     args = parser.parse_args()
 
     root = Path(args.directory)

{datex_studio_cli-0.4.2 → datex_studio_cli-0.4.3}/src/dxs/__init__.py

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

{datex_studio_cli-0.4.2 → datex_studio_cli-0.4.3}/src/dxs/cli.py

@@ -38,6 +38,37 @@ def set_last_output_format(fmt: OutputFormat) -> None:
     _last_output_format = fmt
 
 
+def _format_set_in_env_or_config() -> bool:
+    """Whether ``default_output_format`` was set explicitly outside CLI flags.
+
+    Used to decide if TTY-auto-script mode should override the default format.
+    Returns True when either ``DXS_DEFAULT_OUTPUT_FORMAT`` is in the environment
+    or the config file contains a ``default_output_format`` entry.
+    """
+    import os
+
+    from dxs.utils.config import load_config_file
+
+    if os.environ.get("DXS_DEFAULT_OUTPUT_FORMAT"):
+        return True
+    try:
+        return bool(load_config_file().get("default_output_format"))
+    except Exception:  # noqa: BLE001 - config read should never block startup
+        return False
+
+
+def _stdout_is_pipe() -> bool:
+    """Whether stdout looks like a non-interactive consumer (pipe/redirect).
+
+    Pulled into a helper so tests can patch it independently of Click's
+    CliRunner, which swaps ``sys.stdout`` with a non-TTY StringIO.
+    """
+    try:
+        return not sys.stdout.isatty()
+    except (AttributeError, ValueError):
+        return False
+
+
 # Global options shared across all commands
 CONTEXT_SETTINGS = {
     "help_option_names": ["-h", "--help"],
@@ -140,6 +171,13 @@ class DxsGroup(click.Group):
     default=False,
     help="Show full output including null values and verbose metadata",
 )
+@click.option(
+    "--flat-fv/--no-flat-fv",
+    "flat_fv",
+    default=None,
+    help="Flatten Dynamics @OData FormattedValue siblings into clean keys. "
+    "Defaults to on with --concise (the default mode); pass --no-flat-fv to opt out.",
+)
 @click.option(
     "-s",
     "--save",
@@ -181,6 +219,7 @@ def cli(
     verbose: bool,
     quiet: bool,
     full: bool,
+    flat_fv: bool | None,
     save_path: str | None,
     force_overwrite: bool,
     diagnose_auth: bool,
@@ -229,19 +268,40 @@ def cli(
     # Load settings
     settings = get_settings()
 
-    # Set output format (CLI flag > env var > config > default)
+    # When stdout is not a TTY (piped/redirected), assume a script consumer:
+    # default to JSON output and suppress progress banners unless the user
+    # has explicitly chosen otherwise via CLI flag, env var, or config file.
+    piped = _stdout_is_pipe()
+    click_ctx = click.get_current_context()
+    quiet_src = click_ctx.get_parameter_source("quiet")
+    fmt_explicit_in_env_or_config = _format_set_in_env_or_config()
+
+    # Set output format (CLI flag > env var > config > TTY auto > default)
     if output_format:
         dxs_ctx.output_format = OutputFormat(output_format.lower())
         dxs_ctx.explicit_output_format = True
+    elif fmt_explicit_in_env_or_config and settings.default_output_format:
+        dxs_ctx.output_format = OutputFormat(settings.default_output_format.lower())
+    elif piped:
+        dxs_ctx.output_format = OutputFormat.JSON
     elif settings.default_output_format:
         dxs_ctx.output_format = OutputFormat(settings.default_output_format.lower())
     set_last_output_format(dxs_ctx.output_format)
 
     # Set verbosity (--verbose enables debug output, --quiet suppresses progress)
     dxs_ctx.verbose = verbose
-    dxs_ctx.quiet = quiet
+    if quiet_src == click.core.ParameterSource.COMMANDLINE:
+        dxs_ctx.quiet = quiet
+    else:
+        dxs_ctx.quiet = quiet or piped
     # Concise output is default; --full disables it
     dxs_ctx.concise = not full
+    # Flatten Dynamics FormattedValue siblings: follow --concise unless
+    # --flat-fv / --no-flat-fv was passed explicitly.
+    if flat_fv is None:
+        dxs_ctx.flat_fv = dxs_ctx.concise
+    else:
+        dxs_ctx.flat_fv = flat_fv
 
     # Set save options
     dxs_ctx.save_path = save_path

{datex_studio_cli-0.4.2 → datex_studio_cli-0.4.3}/src/dxs/commands/branch.py

@@ -13,6 +13,7 @@ from dxs.core.api import (
     BranchEndpoints,
     RepoEndpoints,
     SourceControlEndpoints,
+    fetch_settings,
 )
 from dxs.core.api.models import (
     APPLICATION_DEFINITION_TYPE_NAMES,
@@ -1073,11 +1074,7 @@ def settings(ctx: DxsContext, branch_id: int) -> None:
     client = ApiClient()
     ctx.log(f"Fetching settings for branch {branch_id}...")
 
-    settings_data = client.get(BranchEndpoints.settings(branch_id))
-
-    # Normalize to list if not already
-    if not isinstance(settings_data, list):
-        settings_data = [settings_data] if settings_data else []
+    settings_data = fetch_settings(client, branch_id)
 
     ctx.output(list_response(items=settings_data, semantic_key="settings", branch_id=branch_id))
 

{datex_studio_cli-0.4.2 → datex_studio_cli-0.4.3}/src/dxs/commands/configuration.py

@@ -70,7 +70,9 @@ def configuration() -> None:
 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"))
+    ctx.output(
+        single(item={"types": types, "count": len(types)}, semantic_key="configuration_types")
+    )
 
 
 @configuration.command("get")

{datex_studio_cli-0.4.2 → datex_studio_cli-0.4.3}/src/dxs/commands/crm.py

@@ -1318,7 +1318,12 @@ def _list_entities(ctx: "DxsContext") -> None:
     ctx.output(list_response(items=formatted_entities, semantic_key="entities"))
 
 
-def _get_entity_metadata(ctx: "DxsContext", entity_name: str, relationships: bool) -> None:
+def _get_entity_metadata(
+    ctx: "DxsContext",
+    entity_name: str,
+    relationships: bool,
+    search: str | None = None,
+) -> None:
     """Get metadata for a specific entity."""
     client = DynamicsClient()
 
@@ -1342,6 +1347,16 @@ def _get_entity_metadata(ctx: "DxsContext", entity_name: str, relationships: boo
             }
         )
 
+    if search:
+        needle = search.lower()
+        formatted_fields = [
+            f
+            for f in formatted_fields
+            if needle in (f.get("name") or "").lower()
+            or needle in (f.get("display_name") or "").lower()
+            or needle in (f.get("description") or "").lower()
+        ]
+
     # Output fields
     ctx.output(list_response(items=formatted_fields, semantic_key="fields"))
 
@@ -1375,6 +1390,23 @@ def _get_entity_metadata(ctx: "DxsContext", entity_name: str, relationships: boo
                 }
             )
 
+        if search:
+            needle = search.lower()
+            formatted_relationships = [
+                r
+                for r in formatted_relationships
+                if any(
+                    needle in (r.get(k) or "").lower()
+                    for k in (
+                        "name",
+                        "schema_name",
+                        "target_entity",
+                        "referencing_entity",
+                        "referencing_attribute",
+                    )
+                )
+            ]
+
         ctx.output(list_response(items=formatted_relationships, semantic_key="relationships"))
 
 
@@ -1387,9 +1419,22 @@ def _get_entity_metadata(ctx: "DxsContext", entity_name: str, relationships: boo
     default=False,
     help="Include navigation properties (relationships to other entities)",
 )
+@click.option(
+    "--search",
+    "-S",
+    type=str,
+    default=None,
+    help="Filter fields (and relationships) by case-insensitive substring "
+    "match on name, display_name, or description.",
+)
 @click.pass_obj
 @require_auth
-def metadata(ctx: "DxsContext", entity_name: str | None, relationships: bool) -> None:
+def metadata(
+    ctx: "DxsContext",
+    entity_name: str | None,
+    relationships: bool,
+    search: str | None,
+) -> None:
     """Entity metadata exploration.
 
     Explore Dynamics CRM entity definitions, fields, and relationships.
@@ -1409,6 +1454,7 @@ def metadata(ctx: "DxsContext", entity_name: str | None, relationships: bool) ->
         dxs crm metadata account                     # Fields for accounts
         dxs crm metadata incident --relationships    # Include navigation properties
         dxs crm metadata incident -r                 # Short form
+        dxs crm metadata incident --search priority  # Filter fields by keyword
     """
     if entity_name is None:
         # Show help if no argument provided
@@ -1420,13 +1466,56 @@ def metadata(ctx: "DxsContext", entity_name: str | None, relationships: bool) ->
         _list_entities(ctx)
     else:
         # Show fields for the specified entity
-        _get_entity_metadata(ctx, entity_name, relationships)
+        _get_entity_metadata(ctx, entity_name, relationships, search=search)
 
 
 # Register metadata as subcommand of crm
 crm.add_command(metadata)
 
 
+@click.command("picklist")
+@click.argument("entity_name")
+@click.argument("attribute_name")
+@click.pass_obj
+@require_auth
+def picklist(ctx: "DxsContext", entity_name: str, attribute_name: str) -> None:
+    """Show option set (picklist) values for an entity attribute.
+
+    Lists the integer values and labels for a picklist/state/status field.
+    Useful for building OData filters that need numeric picklist values.
+
+    \b
+    Examples:
+        dxs crm picklist incident statuscode
+        dxs crm picklist salesorder statuscode
+        dxs crm picklist incident prioritycode
+    """
+    from dxs.utils.errors import ApiError
+
+    client = DynamicsClient()
+    ctx.log(f"Fetching picklist options for {entity_name}.{attribute_name}...")
+    try:
+        options = client.get_picklist_options(entity_name, attribute_name)
+    except (KeyError, TypeError) as exc:
+        raise ApiError(
+            message=(
+                f"'{attribute_name}' on '{entity_name}' is not a picklist attribute "
+                "(no OptionSet present in the response)."
+            ),
+            code="DXS-DYNAMICS-NOT-PICKLIST",
+            suggestions=[
+                f"Run 'dxs crm metadata {entity_name} --search {attribute_name}' "
+                "to inspect the field's actual type.",
+                "Picklist fields are typically suffixed 'code' (e.g., statuscode, casetypecode).",
+            ],
+        ) from exc
+    ctx.output(list_response(items=options, semantic_key=f"{attribute_name}_options"))
+
+
+# Register picklist as subcommand of crm
+crm.add_command(picklist)
+
+
 # =============================================================================
 # Activity Commands (portal comments, emails)
 # =============================================================================

{datex_studio_cli-0.4.2 → datex_studio_cli-0.4.3}/src/dxs/commands/datasource.py

@@ -37,8 +37,9 @@ from dxs.core.datasource.parsers import (
 )
 from dxs.core.datasource.resolver import apply_linked_params, resolve_linked_ds_metadata
 from dxs.core.datasource.validator import DatasourceValidator
-from dxs.utils.click_options import pagination_options, resolve_branch as _resolve_branch
-from dxs.utils.errors import ApiError, DxsError, ValidationError
+from dxs.utils.click_options import pagination_options
+from dxs.utils.click_options import resolve_branch as _resolve_branch
+from dxs.utils.errors import DxsError, ValidationError
 from dxs.utils.responses import list_response, single
 
 _MAX_FLOW_FILE_BYTES = 512 * 1024  # 512 KB
@@ -85,7 +86,10 @@ def _load_config_json(file: str) -> dict[str, Any]:
         raise ValidationError(
             message=f"Invalid JSON in {file}: {e}",
             code="DXS-DS-003",
-            suggestions=["Check JSON syntax (mismatched brackets, trailing commas)", "Use a JSON validator"],
+            suggestions=[
+                "Check JSON syntax (mismatched brackets, trailing commas)",
+                "Use a JSON validator",
+            ],
         ) from None
 
 
@@ -207,9 +211,7 @@ def _generate_config(
                     "The linked reference will be stored but may cause build errors."
                 )
             except DxsError as exc:
-                ctx.log(
-                    f"Warning: Could not verify target datasource '{target_ref}': {exc}"
-                )
+                ctx.log(f"Warning: Could not verify target datasource '{target_ref}': {exc}")
 
     DatasourceValidator().validate_and_raise(config.model_dump())
 
@@ -493,7 +495,9 @@ def generate(
         raise ValidationError(
             message="Use either --query/-q or --query-file/-Q, not both.",
             code="DXS-DS-010",
-            suggestions=["Use --query/-q for inline queries or --query-file/-Q for file-based queries"],
+            suggestions=[
+                "Use --query/-q for inline queries or --query-file/-Q for file-based queries"
+            ],
         )
     if query_file:
         query = _read_file(query_file, "--query-file").strip()
@@ -501,7 +505,10 @@ def generate(
         raise ValidationError(
             message="Provide either --query/-q or --query-file/-Q.",
             code="DXS-DS-011",
-            suggestions=["Provide an OData query with --query/-q or --query-file/-Q", "See examples: dxs datasource generate --help"],
+            suggestions=[
+                "Provide an OData query with --query/-q or --query-file/-Q",
+                "See examples: dxs datasource generate --help",
+            ],
         )
 
     ctx.log(f"Generating datasource configuration for: {query[:80]}...")
@@ -539,9 +546,7 @@ def generate(
 
     config_dict = config.model_dump(by_alias=True, mode="python", exclude_none=False)
     output_path = Path(output_file)
-    output_path.write_text(
-        json_lib.dumps(config_dict, indent=2, default=str), encoding="utf-8"
-    )
+    output_path.write_text(json_lib.dumps(config_dict, indent=2, default=str), encoding="utf-8")
 
     output_item: dict[str, Any] = {
         "referenceName": reference_name,
@@ -580,7 +585,10 @@ def upsert(ctx: DxsContext, file: str, branch: int | None) -> None:
         raise ValidationError(
             message=f"File {file} is missing 'referenceName'. Use 'dxs datasource generate' to create valid config files.",
             code="DXS-DS-012",
-            suggestions=["Use 'dxs datasource generate' to create a valid config file", "Manually add 'referenceName' to the JSON"],
+            suggestions=[
+                "Use 'dxs datasource generate' to create a valid config file",
+                "Manually add 'referenceName' to the JSON",
+            ],
         )
 
     api_client = ApiClient()
@@ -864,7 +872,9 @@ def generate_flow(
         raise ValidationError(
             message="--collection and --single are mutually exclusive",
             code="DXS-DS-013",
-            suggestions=["Use --collection for collection result or --single for single entity, not both"],
+            suggestions=[
+                "Use --collection for collection result or --single for single entity, not both"
+            ],
         )
 
     # Determine result_is_collection (None = auto-detect in generator)
@@ -900,7 +910,10 @@ def generate_flow(
         raise ValidationError(
             message=f"--type-def must contain a YAML/JSON list of type definitions, got {type(type_def_raw).__name__}",
             code="DXS-DS-005",
-            suggestions=["Ensure --type-def file contains a top-level list/array", "Example: [{id: Id, type: number}, ...]"],
+            suggestions=[
+                "Ensure --type-def file contains a top-level list/array",
+                "Example: [{id: Id, type: number}, ...]",
+            ],
         )
     try:
         type_def_parsed = parse_type_def(type_def_raw)
@@ -908,7 +921,10 @@ def generate_flow(
         raise ValidationError(
             message=str(e),
             code="DXS-DS-006",
-            suggestions=["Check type definition format", "See: dxs datasource generate-flow --help"],
+            suggestions=[
+                "Check type definition format",
+                "See: dxs datasource generate-flow --help",
+            ],
         ) from None
 
     # 4. Parse --in-param
@@ -926,7 +942,10 @@ def generate_flow(
                 raise ValidationError(
                     message=f"--key must be 'name:type', got: {k!r}",
                     code="DXS-DS-014",
-                    suggestions=["Format: name:type (e.g. Id:number)", "Use --key Id:number --key Code:string"],
+                    suggestions=[
+                        "Format: name:type (e.g. Id:number)",
+                        "Use --key Id:number --key Code:string",
+                    ],
                 )
             parsed_keys.append((parts[0], parts[1]))
 
@@ -990,9 +1009,7 @@ def generate_flow(
                     "The linked reference will be stored but may cause build errors."
                 )
             except DxsError as exc:
-                ctx.log(
-                    f"Warning: Could not verify target datasource '{target_ref}': {exc}"
-                )
+                ctx.log(f"Warning: Could not verify target datasource '{target_ref}': {exc}")
 
     # 11. Validate the final configuration
     DatasourceValidator().validate_and_raise(config.model_dump())
@@ -1000,9 +1017,7 @@ def generate_flow(
     # Serialize to JSON
     config_dict = config.model_dump(by_alias=True, mode="python", exclude_none=False)
     output_path = Path(output_file)
-    output_path.write_text(
-        json_lib.dumps(config_dict, indent=2, default=str), encoding="utf-8"
-    )
+    output_path.write_text(json_lib.dumps(config_dict, indent=2, default=str), encoding="utf-8")
 
     output_item: dict[str, Any] = {
         "referenceName": reference_name,
@@ -1226,7 +1241,10 @@ def delete(
         raise ValidationError(
             message="Provide a reference name or --id.",
             code="DXS-DS-015",
-            suggestions=["Provide reference name: dxs datasource delete ds_name -b 123", "Or use --id: dxs datasource delete --id 456 -b 123"],
+            suggestions=[
+                "Provide reference name: dxs datasource delete ds_name -b 123",
+                "Or use --id: dxs datasource delete --id 456 -b 123",
+            ],
         )
 
     api_client = ApiClient()