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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datex-studio-cli
-Version: 0.4.5
+Version: 0.4.6
 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.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "datex-studio-cli"
-version = "0.4.5"
+version = "0.4.6"
 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.6}/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.6"
 __app_name__ = "dxs"

{datex_studio_cli-0.4.5 → datex_studio_cli-0.4.6}/src/dxs/commands/crm.py

@@ -505,32 +505,60 @@ def _format_annotation(annotation: dict[str, Any]) -> dict[str, Any]:
 
 @click.group()
 def crm() -> None:
-    """Dynamics CRM commands.
+    """Dynamics CRM / Dataverse commands.
 
-    Commands for interacting with Dynamics CRM / Dataverse.
+    Query support cases, accounts, and activities - or run raw OData against
+    any Dataverse entity.
 
     \b
     Setup (one-time):
-        1. Configure your CRM URL:
-           dxs config set dynamics_crm_url https://yourorg.crm.dynamics.com
-        2. Login to grant Dynamics CRM consent:
-           dxs auth login
+        dxs config set dynamics_crm_url https://yourorg.crm.dynamics.com
+        dxs auth login        # grant Dynamics CRM consent
 
     \b
-    Available subcommands:
-        account   Account (company) management
-        activity  Activity queries (portal comments, emails)
-        case      Support case (incident) management
-        odata     Generic OData query against any Dataverse entity
+    Pick a command:
+        case       Support cases (incidents): search, get, query, types
+        account    Accounts (companies): list, search
+        activity   Portal comments & emails - by date range or ticket
+        metadata   Discover entities, fields, and relationships
+        picklist   Resolve option-set (picklist) integer values <-> labels
+        odata      Raw OData against ANY entity (escape hatch)
+
+    \b
+    Exploring an unfamiliar org/entity? Discover schema before you query:
+        1. dxs crm metadata entities --search <keyword>   # find the entity
+        2. dxs crm metadata <entity>  --search <keyword>  # find field names
+        3. dxs crm picklist <entity> <field>              # enum values for filters
+        4. dxs crm odata <entity> -f "<filter>" --count-only   # size it first
+        5. dxs crm odata <entity> -f "<filter>" -s "<fields>" --limit 25
+
+    \b
+    Working efficiently (keeps responses small - matters for agents):
+        - Prefer case/account/activity over odata: they pre-select fields
+          and format output (HTML->markdown, lookups resolved).
+        - WITHOUT --limit, queries auto-paginate and return ALL matching
+          rows. Set --limit, or run --count-only first to size the result.
+        - Always narrow odata with -f/--filter and -s/--select.
+        - metadata is capped at 10 rows; use --search/--skip, not blind dumps.
+        - Output is concise by default; pass global --full only when needed.
     """
     pass
 
 
 @click.group()
 def case() -> None:
-    """Support case commands.
+    """Support case (incident) commands.
+
+    Search and read support cases. These helpers pre-select sensible fields
+    and convert HTML descriptions/notes to markdown - prefer them over
+    'dxs crm odata incidents' for everyday case work.
 
-    Search and view support cases (incidents) from Dynamics CRM.
+    \b
+    Subcommands:
+        search  Find cases by text, account, status, date, or type
+        get     Fetch one case by ticket number (+ activity / notes)
+        query   Custom OData over incidents (full field control)
+        types   List case-type picklist values
 
     \b
     Examples:
@@ -538,7 +566,8 @@ def case() -> None:
         dxs crm case get C260303_0017 --include-activity   # With comments & emails
         dxs crm case search "shipping"                     # Search all cases
         dxs crm case search "CAS-001"                      # Search by case number
-        dxs crm case search --status active                # List active cases
+        dxs crm case search --status active --limit 25     # Cap the result
+        dxs crm case search --account "Contoso" --count-only   # Size before fetching
     """
     pass
 
@@ -1092,15 +1121,17 @@ def _format_account(account: dict[str, Any]) -> dict[str, Any]:
 
 @click.group()
 def account() -> None:
-    """Account commands.
+    """Account (company) commands.
 
-    List and search for accounts (companies) in Dynamics CRM.
+    List and search accounts. Returns active accounts with a curated field
+    set; for other account fields drop down to 'dxs crm odata accounts'.
 
     \b
     Examples:
-        dxs crm account list                  # List accounts
+        dxs crm account list --limit 25       # First 25 (omit --limit = ALL)
         dxs crm account search "Contoso"      # Search by name
         dxs crm account search "Texas" -l 10  # Search with limit
+        dxs crm account list --count-only     # Just the count
     """
     pass
 
@@ -1292,8 +1323,67 @@ def _get_localized_label(obj: dict[str, Any] | None) -> str | None:
     return None
 
 
-def _list_entities(ctx: "DxsContext") -> None:
-    """List all entity definitions in Dynamics CRM."""
+# Default page size for metadata exploration. Entity catalogs and attribute
+# lists are large enough to blow out an agent's context window if returned in
+# full, so callers must opt into more via --limit/--skip (or --limit 0 for all).
+DEFAULT_METADATA_LIMIT = 10
+
+
+def _paginate_metadata(
+    items: list[dict[str, Any]],
+    limit: int | None,
+    skip: int,
+) -> tuple[list[dict[str, Any]], dict[str, Any]]:
+    """Window a metadata list by skip/limit and build pagination metadata.
+
+    Applies ``DEFAULT_METADATA_LIMIT`` when ``limit`` is None so unbounded
+    metadata listings can't flood the caller's context. ``limit <= 0`` means
+    "no limit" (return everything from ``skip`` onward).
+
+    Args:
+        items: Full list of formatted metadata records (after any search filter).
+        limit: Page size, or None to apply the default, or <= 0 for unlimited.
+        skip: Number of records to skip from the start.
+
+    Returns:
+        Tuple of (page, metadata_kwargs). ``metadata_kwargs`` carries
+        ``total_count`` (matched before windowing), ``skip``, ``limit``,
+        ``has_more``, and a ``pagination_hint`` string when truncated.
+    """
+    effective_limit = DEFAULT_METADATA_LIMIT if limit is None else limit
+    matched = len(items)
+    skip = max(skip, 0)
+
+    if effective_limit <= 0:
+        page = items[skip:]
+    else:
+        page = items[skip : skip + effective_limit]
+
+    end = skip + len(page)
+    has_more = end < matched
+
+    meta: dict[str, Any] = {
+        "total_count": matched,
+        "skip": skip,
+        "limit": effective_limit if effective_limit > 0 else None,
+        "has_more": has_more,
+    }
+    if has_more:
+        meta["pagination_hint"] = (
+            f"Showing {skip + 1}-{end} of {matched}. "
+            f"Use --skip {end} for the next page, --limit 0 for all, "
+            "or --search <text> to narrow."
+        )
+    return page, meta
+
+
+def _list_entities(
+    ctx: "DxsContext",
+    search: str | None = None,
+    limit: int | None = None,
+    skip: int = 0,
+) -> None:
+    """List entity definitions in Dynamics CRM (search + paginate)."""
     client = DynamicsClient()
 
     ctx.log("Fetching entity definitions...")
@@ -1315,19 +1405,32 @@ def _list_entities(ctx: "DxsContext") -> None:
             }
         )
 
-    ctx.output(list_response(items=formatted_entities, semantic_key="entities"))
+    if search:
+        needle = search.lower()
+        formatted_entities = [
+            e
+            for e in formatted_entities
+            if needle in (e.get("name") or "").lower()
+            or needle in (e.get("display_name") or "").lower()
+            or needle in (e.get("description") or "").lower()
+        ]
+
+    page, page_meta = _paginate_metadata(formatted_entities, limit, skip)
 
+    ctx.output(list_response(items=page, semantic_key="entities", **page_meta))
 
-def _get_entity_metadata(
+
+def _get_entity_fields(
     ctx: "DxsContext",
     entity_name: str,
-    relationships: bool,
     search: str | None = None,
+    limit: int | None = None,
+    skip: int = 0,
 ) -> None:
-    """Get metadata for a specific entity."""
+    """Output the field/attribute metadata for an entity (search + paginate)."""
     client = DynamicsClient()
 
-    ctx.log(f"Fetching metadata for '{entity_name}'...")
+    ctx.log(f"Fetching fields for '{entity_name}'...")
 
     result = client.get_entity_fields(entity_name)
 
@@ -1357,57 +1460,71 @@ def _get_entity_metadata(
             or needle in (f.get("description") or "").lower()
         ]
 
-    # Output fields
-    ctx.output(list_response(items=formatted_fields, semantic_key="fields"))
-
-    # Add relationships if requested
-    if relationships:
-        ctx.log("Fetching relationships...")
-        rels = client.get_entity_relationships(entity_name)
-
-        formatted_relationships = []
-
-        # Format ManyToOne relationships (lookups - this entity references another)
-        for rel in rels.get("many_to_one", []):
-            formatted_relationships.append(
-                {
-                    "name": rel.get("ReferencingAttribute"),
-                    "schema_name": rel.get("SchemaName"),
-                    "target_entity": rel.get("ReferencedEntity"),
-                    "target_attribute": rel.get("ReferencedAttribute"),
-                    "type": "ManyToOne",
-                }
-            )
+    field_page, field_meta = _paginate_metadata(formatted_fields, limit, skip)
+    ctx.output(list_response(items=field_page, semantic_key="fields", **field_meta))
 
-        # Format OneToMany relationships (this entity is referenced by others)
-        for rel in rels.get("one_to_many", []):
-            formatted_relationships.append(
-                {
-                    "name": rel.get("SchemaName"),
-                    "referencing_entity": rel.get("ReferencingEntity"),
-                    "referencing_attribute": rel.get("ReferencingAttribute"),
-                    "type": "OneToMany",
-                }
-            )
 
-        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",
-                    )
+def _get_entity_relationships(
+    ctx: "DxsContext",
+    entity_name: str,
+    search: str | None = None,
+    limit: int | None = None,
+    skip: int = 0,
+) -> None:
+    """Output ONLY the relationship metadata for an entity (search + paginate).
+
+    Relationships are returned on their own — fields are not mixed in — so the
+    output (and skip/limit windowing) stays unambiguous.
+    """
+    client = DynamicsClient()
+
+    ctx.log(f"Fetching relationships for '{entity_name}'...")
+    rels = client.get_entity_relationships(entity_name)
+
+    formatted_relationships = []
+
+    # Format ManyToOne relationships (lookups - this entity references another)
+    for rel in rels.get("many_to_one", []):
+        formatted_relationships.append(
+            {
+                "name": rel.get("ReferencingAttribute"),
+                "schema_name": rel.get("SchemaName"),
+                "target_entity": rel.get("ReferencedEntity"),
+                "target_attribute": rel.get("ReferencedAttribute"),
+                "type": "ManyToOne",
+            }
+        )
+
+    # Format OneToMany relationships (this entity is referenced by others)
+    for rel in rels.get("one_to_many", []):
+        formatted_relationships.append(
+            {
+                "name": rel.get("SchemaName"),
+                "referencing_entity": rel.get("ReferencingEntity"),
+                "referencing_attribute": rel.get("ReferencingAttribute"),
+                "type": "OneToMany",
+            }
+        )
+
+    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"))
+    rel_page, rel_meta = _paginate_metadata(formatted_relationships, limit, skip)
+    ctx.output(list_response(items=rel_page, semantic_key="relationships", **rel_meta))
 
 
 @click.command("metadata")
@@ -1417,16 +1534,30 @@ def _get_entity_metadata(
     "-r",
     is_flag=True,
     default=False,
-    help="Include navigation properties (relationships to other entities)",
+    help="Return ONLY the entity's relationships (navigation properties) "
+    "instead of its fields. Requires a specific entity (not 'entities').",
 )
 @click.option(
     "--search",
     "-S",
     type=str,
     default=None,
-    help="Filter fields (and relationships) by case-insensitive substring "
+    help="Filter entities/fields/relationships by case-insensitive substring "
     "match on name, display_name, or description.",
 )
+@click.option(
+    "--limit",
+    "-l",
+    type=int,
+    default=None,
+    help=f"Max records to return (default: {DEFAULT_METADATA_LIMIT}). Use 0 for no limit.",
+)
+@click.option(
+    "--skip",
+    type=int,
+    default=0,
+    help="Number of records to skip (for paging past the default limit).",
+)
 @click.pass_obj
 @require_auth
 def metadata(
@@ -1434,6 +1565,8 @@ def metadata(
     entity_name: str | None,
     relationships: bool,
     search: str | None,
+    limit: int | None,
+    skip: int,
 ) -> None:
     """Entity metadata exploration.
 
@@ -1441,7 +1574,14 @@ def metadata(
     Useful for understanding the data model and constructing OData queries.
 
     Use "entities" as the argument to list all available entities.
-    Use any other entity name to show its fields.
+    Use any other entity name to show its fields, or add --relationships to
+    show its relationships instead. Fields and relationships are never mixed
+    in one response.
+
+    Results are capped at 10 records by default to protect your context
+    window. Narrow with --search, page with --skip, or pass --limit 0 to
+    return everything. The response metadata reports total_count, has_more,
+    and a pagination_hint when results are truncated.
 
     \b
     Arguments:
@@ -1449,10 +1589,12 @@ def metadata(
 
     \b
     Examples:
-        dxs crm metadata entities                    # List all entities
-        dxs crm metadata incident                    # Fields for cases
-        dxs crm metadata account                     # Fields for accounts
-        dxs crm metadata incident --relationships    # Include navigation properties
+        dxs crm metadata entities                    # First 10 entities
+        dxs crm metadata entities --search shipment  # Find entities by keyword
+        dxs crm metadata entities --skip 10          # Next page of entities
+        dxs crm metadata incident                    # First 10 fields for cases
+        dxs crm metadata incident --limit 0          # ALL fields (no cap)
+        dxs crm metadata incident --relationships    # ONLY relationships (not fields)
         dxs crm metadata incident -r                 # Short form
         dxs crm metadata incident --search priority  # Filter fields by keyword
     """
@@ -1462,11 +1604,26 @@ def metadata(
         return
 
     if entity_name == "entities":
+        if relationships:
+            from dxs.utils.errors import ValidationError
+
+            raise ValidationError(
+                message="--relationships requires a specific entity, not 'entities'.",
+                code="DXS-CRM-002",
+                suggestions=[
+                    "List entities first: dxs crm metadata entities --search <keyword>",
+                    "Then inspect one entity's relationships: "
+                    "dxs crm metadata <entity> --relationships",
+                ],
+            )
         # Special case: list all entities
-        _list_entities(ctx)
+        _list_entities(ctx, search=search, limit=limit, skip=skip)
+    elif relationships:
+        # Show ONLY relationships for the specified entity (fields not mixed in)
+        _get_entity_relationships(ctx, entity_name, search=search, limit=limit, skip=skip)
     else:
         # Show fields for the specified entity
-        _get_entity_metadata(ctx, entity_name, relationships, search=search)
+        _get_entity_fields(ctx, entity_name, search=search, limit=limit, skip=skip)
 
 
 # Register metadata as subcommand of crm
@@ -1481,8 +1638,10 @@ crm.add_command(metadata)
 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.
+    Lists the integer values and labels for a picklist/state/status field -
+    use these numbers when building OData --filter expressions (e.g.
+    'statecode eq 0'). Picklist fields are usually suffixed 'code'; find
+    candidates with 'dxs crm metadata <entity> --search code'.
 
     \b
     Examples:
@@ -1762,12 +1921,17 @@ def _activity_ticket_options(f: Any) -> Any:
 def activity() -> None:
     """Activity queries (portal comments, emails).
 
-    Query customer-authored activities across all cases or for a specific ticket.
+    Query customer-authored activities across all cases (by date range) or
+    for a specific ticket. HTML bodies are stripped to plain text and
+    truncated for token-efficient sentiment scanning.
+
+    \b
+    Subcommands:
+        portalcomment  Portal comment queries (query | ticket)
+        email          Email queries (query | ticket)
 
     \b
-    Available subcommands:
-        portalcomment  Portal comment queries
-        email          Email queries
+    Tip: 'query' requires --since; add --count-only to size a range first.
     """
     pass
 
@@ -2238,14 +2402,17 @@ def crm_odata(
     batch_size: int | None,
     count_only: bool,
 ) -> None:
-    """Execute an OData query against any Dataverse entity.
+    """Execute a raw OData query against any Dataverse entity.
+
+    The escape hatch for entities/fields the case/account/activity helpers
+    don't cover. Returns raw API data with no field curation or HTML
+    conversion - discover field names first with 'dxs crm metadata <entity>'.
 
     ENTITY is the entity path without leading slash (e.g., contacts,
     annotations, EntityDefinitions(...)/Attributes(...)).
 
-    Returns raw API response data — no formatting or HTML conversion.
-    Use this for exploring picklist metadata, querying arbitrary entities,
-    or running Dataverse queries beyond the built-in case/account commands.
+    WARNING: without --limit this auto-paginates and returns ALL matching
+    rows. Run --count-only first, then set --limit.
 
     \b
     Examples: