datex-studio-cli 0.4.12__tar.gz → 0.4.14__tar.gz

{datex_studio_cli-0.4.12 → datex_studio_cli-0.4.14}/.gitignore

@@ -99,3 +99,6 @@ Thumbs.db
 /reports/
 test-preview.svg
 test-preview.svg
+
+# CAC working copies (dxs ng harnesses) — never committed
+/components/

{datex_studio_cli-0.4.12 → datex_studio_cli-0.4.14}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: datex-studio-cli
-Version: 0.4.12
+Version: 0.4.14
 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
@@ -247,6 +247,7 @@ Direct commands on the `source` group:
 | `locks` | Show current lock status |
 | `deps <ref>` | Show configuration dependencies |
 | `deps-diff` | Show dependency changes between versions |
+| `referenced-from <pkg>` | List packages/apps that reference a package |
 | `workitems` | Extract work items from commit messages |
 | `compare` | Compare two branches |
 | `graph` | Show dependency graph |
@@ -278,7 +279,8 @@ dxs source compare --source 100 --target 200
 | `show <id>` | Show branch details |
 | `create` | Create a new feature branch |
 | `delete <id>` | Delete a feature branch |
-| `publish <id>` | Publish branch to marketplace |
+| `commit <id>` | Commit (merge) a feature branch into its Main branch |
+| `publish <id>` | Publish branch to marketplace (`--notes` is **required**) |
 | `baseline <id>` | Find baseline (previous release) |
 | `search <query>` | Search branches by name |
 | `roles <id>` | Show branch roles |
@@ -305,6 +307,83 @@ dxs source branch list --repo 10 --with-changes
 dxs source branch list --repo 10 --sort modified --desc
 ```
 
+### Package References (`dxs source reference`)
+
+| Command | Description |
+|---------|-------------|
+| `set` | Re-pin a direct package reference and rebuild transitive references |
+
+```bash
+# Pin Module1 to a newly published version on feature branch 3101
+dxs source reference set -b 3101 -p Module1 -v 20260714.1000
+```
+
+Rebuilds the branch's flattened reference list after the bump and refuses the
+write if the result would contain a version conflict (the same package pinned at
+two versions) or a circular reference.
+
+### Package Cascade (`dxs source cascade`)
+
+When a package is republished, every package that references it stays pinned to
+the old version until it is re-pinned and republished itself. The cascade
+automates that fan-out.
+
+| Command | Description |
+|---------|-------------|
+| `plan` | Compute the ordered set of packages to re-pin + republish |
+| `run` | Execute a plan bottom-up (branch → re-pin → commit → publish) |
+
+```bash
+# 1. Plan the cascade from a package you just published
+dxs source cascade plan -p Module1 -v 20260714.1000 -O json > plan.json
+
+# 2. Review what it would do — mutates nothing
+dxs source cascade run --plan plan.json --dry-run
+
+# 3. Execute
+dxs source cascade run --plan plan.json
+```
+
+`plan` walks reverse-references from the origin package and emits update nodes
+grouped into topological levels, plus a `staleApplications` list — applications
+that consume an affected package but cannot be cascaded automatically.
+
+- `--org` scopes traversal to a single organization. **Omit it and the cascade
+  spans consumers across all organizations**, which is rarely what you want.
+- `--max-depth` limits how far the traversal follows the reference chain.
+
+`run` executes each level bottom-up, feeding each package's newly published
+version forward to its dependents.
+
+Before mutating anything it applies the same guardrails as `branch publish`:
+each node's Main branch is resolved to its owning organization and checked
+against the current identity (once per distinct organization), then the run is
+confirmed. Each re-pinned feature branch is validated before it is committed, so
+a broken reference set never reaches Main or the marketplace.
+
+- `--dry-run` prints the resolved execution order and mutates nothing.
+- `--yes` / `-y` skips the confirmation prompt — use this for unattended runs.
+  Branch validation still runs.
+- `--force` / `-f` skips both the confirmation prompt and branch validation.
+- `--select` restricts the run to named packages (repeatable). Deselecting an
+  intermediate dependency will fail the run, since its dependents need the
+  version it would have produced.
+- `--release-notes` sets the notes for every republish; otherwise a summary of
+  the re-pins is used.
+
+A node whose dependencies are all already at their target version is skipped
+rather than republished for zero change, and its dependents treat it as a no-op
+instead of failing.
+
+Publishing can block on a build, so the publish step uses the longer
+`publish_timeout` setting (default 300s) rather than `api_timeout`. If that call
+still times out, the version is confirmed by looking up the exact
+`(package, version)` pair in the marketplace — the record is committed before the
+build runs, so a timed-out publish has usually still landed.
+
+`cascade run` and `reference set` are both blocked when
+`DXS_RESTRICTED_MODE=true`.
+
 ### Repository Management (`dxs source repo`)
 
 | Command | Description |
@@ -608,11 +687,22 @@ dxs odata execute -c 1 -q "Products?\$select=Id,Name,Price&\$top=10"
 
 | Command | Description |
 |---------|-------------|
-| `list` | List marketplace applications |
+| `list` | List marketplace packages available to your org |
 | `show <id>` | Show application details |
 | `versions <id>` | List published versions |
 | `version <id>` | Show version details |
-| `search <query>` | Search applications |
+| `search <query>` | Search available packages by name/description |
+
+`list` and `search` mirror the Manager > Marketplace screen: they show packages
+available to a consumer organization, each with an `included` flag indicating
+whether that org already has access.
+
+- `--type` selects the marketplace application type, defaulting to
+  `componentmodule`. Other types (`web`, `mobile`, `api`, `portal`,
+  `footprintapi`, `taskscheduler`) are accepted but are not what the Marketplace
+  screen shows.
+- `--org` is the *consumer* organization being browsed on behalf of, not a
+  result filter. Omit it to browse as your own organization.
 
 ### Azure DevOps (`dxs devops`)
 

{datex_studio_cli-0.4.12 → datex_studio_cli-0.4.14}/README.md

@@ -194,6 +194,7 @@ Direct commands on the `source` group:
 | `locks` | Show current lock status |
 | `deps <ref>` | Show configuration dependencies |
 | `deps-diff` | Show dependency changes between versions |
+| `referenced-from <pkg>` | List packages/apps that reference a package |
 | `workitems` | Extract work items from commit messages |
 | `compare` | Compare two branches |
 | `graph` | Show dependency graph |
@@ -225,7 +226,8 @@ dxs source compare --source 100 --target 200
 | `show <id>` | Show branch details |
 | `create` | Create a new feature branch |
 | `delete <id>` | Delete a feature branch |
-| `publish <id>` | Publish branch to marketplace |
+| `commit <id>` | Commit (merge) a feature branch into its Main branch |
+| `publish <id>` | Publish branch to marketplace (`--notes` is **required**) |
 | `baseline <id>` | Find baseline (previous release) |
 | `search <query>` | Search branches by name |
 | `roles <id>` | Show branch roles |
@@ -252,6 +254,83 @@ dxs source branch list --repo 10 --with-changes
 dxs source branch list --repo 10 --sort modified --desc
 ```
 
+### Package References (`dxs source reference`)
+
+| Command | Description |
+|---------|-------------|
+| `set` | Re-pin a direct package reference and rebuild transitive references |
+
+```bash
+# Pin Module1 to a newly published version on feature branch 3101
+dxs source reference set -b 3101 -p Module1 -v 20260714.1000
+```
+
+Rebuilds the branch's flattened reference list after the bump and refuses the
+write if the result would contain a version conflict (the same package pinned at
+two versions) or a circular reference.
+
+### Package Cascade (`dxs source cascade`)
+
+When a package is republished, every package that references it stays pinned to
+the old version until it is re-pinned and republished itself. The cascade
+automates that fan-out.
+
+| Command | Description |
+|---------|-------------|
+| `plan` | Compute the ordered set of packages to re-pin + republish |
+| `run` | Execute a plan bottom-up (branch → re-pin → commit → publish) |
+
+```bash
+# 1. Plan the cascade from a package you just published
+dxs source cascade plan -p Module1 -v 20260714.1000 -O json > plan.json
+
+# 2. Review what it would do — mutates nothing
+dxs source cascade run --plan plan.json --dry-run
+
+# 3. Execute
+dxs source cascade run --plan plan.json
+```
+
+`plan` walks reverse-references from the origin package and emits update nodes
+grouped into topological levels, plus a `staleApplications` list — applications
+that consume an affected package but cannot be cascaded automatically.
+
+- `--org` scopes traversal to a single organization. **Omit it and the cascade
+  spans consumers across all organizations**, which is rarely what you want.
+- `--max-depth` limits how far the traversal follows the reference chain.
+
+`run` executes each level bottom-up, feeding each package's newly published
+version forward to its dependents.
+
+Before mutating anything it applies the same guardrails as `branch publish`:
+each node's Main branch is resolved to its owning organization and checked
+against the current identity (once per distinct organization), then the run is
+confirmed. Each re-pinned feature branch is validated before it is committed, so
+a broken reference set never reaches Main or the marketplace.
+
+- `--dry-run` prints the resolved execution order and mutates nothing.
+- `--yes` / `-y` skips the confirmation prompt — use this for unattended runs.
+  Branch validation still runs.
+- `--force` / `-f` skips both the confirmation prompt and branch validation.
+- `--select` restricts the run to named packages (repeatable). Deselecting an
+  intermediate dependency will fail the run, since its dependents need the
+  version it would have produced.
+- `--release-notes` sets the notes for every republish; otherwise a summary of
+  the re-pins is used.
+
+A node whose dependencies are all already at their target version is skipped
+rather than republished for zero change, and its dependents treat it as a no-op
+instead of failing.
+
+Publishing can block on a build, so the publish step uses the longer
+`publish_timeout` setting (default 300s) rather than `api_timeout`. If that call
+still times out, the version is confirmed by looking up the exact
+`(package, version)` pair in the marketplace — the record is committed before the
+build runs, so a timed-out publish has usually still landed.
+
+`cascade run` and `reference set` are both blocked when
+`DXS_RESTRICTED_MODE=true`.
+
 ### Repository Management (`dxs source repo`)
 
 | Command | Description |
@@ -555,11 +634,22 @@ dxs odata execute -c 1 -q "Products?\$select=Id,Name,Price&\$top=10"
 
 | Command | Description |
 |---------|-------------|
-| `list` | List marketplace applications |
+| `list` | List marketplace packages available to your org |
 | `show <id>` | Show application details |
 | `versions <id>` | List published versions |
 | `version <id>` | Show version details |
-| `search <query>` | Search applications |
+| `search <query>` | Search available packages by name/description |
+
+`list` and `search` mirror the Manager > Marketplace screen: they show packages
+available to a consumer organization, each with an `included` flag indicating
+whether that org already has access.
+
+- `--type` selects the marketplace application type, defaulting to
+  `componentmodule`. Other types (`web`, `mobile`, `api`, `portal`,
+  `footprintapi`, `taskscheduler`) are accepted but are not what the Marketplace
+  screen shows.
+- `--org` is the *consumer* organization being browsed on behalf of, not a
+  result filter. Omit it to browse as your own organization.
 
 ### Azure DevOps (`dxs devops`)
 

{datex_studio_cli-0.4.12 → datex_studio_cli-0.4.14}/pyproject.toml

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

{datex_studio_cli-0.4.12 → datex_studio_cli-0.4.14}/src/dxs/__init__.py

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

{datex_studio_cli-0.4.12 → datex_studio_cli-0.4.14}/src/dxs/cli.py

@@ -70,6 +70,29 @@ def _stdout_is_pipe() -> bool:
         return False
 
 
+def _ensure_utf8_streams() -> None:
+    """Force stdout/stderr to UTF-8 so non-ASCII output never crashes the CLI.
+
+    On Windows a piped or redirected stream defaults to the locale encoding
+    (typically cp1252), which cannot represent characters such as U+2192 (the
+    arrow used in help text like ``dxs source cascade -h`` and in ``cascade
+    run`` progress logs). Writing them raises ``UnicodeEncodeError`` and aborts
+    the command. Reconfiguring to UTF-8 at entry is lossless and idempotent.
+
+    Streams that do not support reconfiguration (already detached, or a test
+    double) are left untouched.
+    """
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is None:
+            continue
+        try:
+            reconfigure(encoding="utf-8")
+        except (ValueError, OSError):
+            # Reconfiguration is unsupported for this stream; leave it as-is.
+            pass
+
+
 # Global options shared across all commands
 CONTEXT_SETTINGS = {
     "help_option_names": ["-h", "--help"],
@@ -498,10 +521,12 @@ def register_commands() -> None:
         function,
         init,
         marketplace,
+        ng,
         odata,
         organization,
         proxy,
         report,
+        reset,
         source,
         studio,
         user,
@@ -520,10 +545,12 @@ def register_commands() -> None:
     cli.add_command(env.env)
     cli.add_command(function.function)
     cli.add_command(marketplace.marketplace)
+    cli.add_command(ng.ng)
     cli.add_command(odata.odata)
     cli.add_command(organization.organization)
     cli.add_command(proxy.proxy)
     cli.add_command(report.report)
+    cli.add_command(reset.reset)
     cli.add_command(source.source)
     cli.add_command(studio.studio)
     cli.add_command(user.user)
@@ -632,6 +659,7 @@ register_commands()
 # Main entry point
 def main() -> None:
     """Main entry point for the CLI."""
+    _ensure_utf8_streams()
     try:
         try:
             cli()

{datex_studio_cli-0.4.12 → datex_studio_cli-0.4.14}/src/dxs/commands/auth.py

@@ -1,8 +1,10 @@
 """Authentication commands: dxs auth [login|logout|status|list|switch]."""
 
+import secrets
 from collections.abc import Callable
 from datetime import datetime, timedelta, timezone
 from typing import Any
+from urllib.parse import urlencode
 
 import click
 
@@ -10,6 +12,7 @@ from dxs.context import DxsContext, pass_context
 from dxs.core.auth import MSALClient, MultiIdentityTokenCache
 from dxs.core.auth.datex_tenant import claims_are_datex, is_datex_identity
 from dxs.core.auth.decorators import get_access_token
+from dxs.core.auth.tenants import org_needs_tenant_login, tenant_authority_for
 from dxs.core.auth.token_cache import CachedIdentity, get_identity_override
 from dxs.core.footprint import get_footprint_token
 from dxs.utils.errors import AuthenticationError, ValidationError
@@ -48,19 +51,27 @@ def run_standard_device_login(
     *,
     tenant_id: str | None = None,
     domain: str | None = None,
+    external_entra_id: bool | None = None,
     organization_id: int | None = None,
     organization_name: str | None = None,
     api_base_url: str | None = None,
 ) -> CachedIdentity:
     """Run the multi-resource device-code login and save the identity.
 
-    Shared by `dxs auth login`, `dxs auth switch` (external tenant) and `dxs init`.
+    Shared by `dxs auth login`, `dxs auth switch` (foreign tenant) and `dxs init`.
 
-    When ``tenant_id`` is given, authenticates against that external Entra tenant
-    (Footprint-only additional scopes) and persists the identity as external.
-    Otherwise authenticates against the configured home tenant with the full
-    additional-scope set. Org id/name are discovered from ``/organizations/mine``
-    unless ``organization_id`` is supplied (staff switch already knows them).
+    When ``tenant_id`` is given, authenticates against that Entra tenant
+    (Footprint-only additional scopes). Otherwise authenticates against the
+    configured home tenant with the full additional-scope set. Org id/name are
+    discovered from ``/organizations/mine`` unless ``organization_id`` is
+    supplied (staff switch already knows them).
+
+    ``external_entra_id`` records whether the org has a *dedicated* Entra
+    External ID tenant, and is stored verbatim rather than inferred from
+    ``tenant_id``: a customer on their own corporate tenant needs a tenant-scoped
+    login while the flag stays False. Callers that do not know the org record
+    (the ``--tenant-id`` self-service path) leave it None, and it falls back to
+    the historical "a tenant was supplied" inference.
 
     ``api_base_url`` pins the environment used for that org discovery — callers
     that target a non-default environment (e.g. ``dxs init --target qa``) must
@@ -71,7 +82,7 @@ def run_standard_device_login(
 
     cache = MultiIdentityTokenCache()
     settings = get_settings()
-    external = tenant_id is not None
+    external = (tenant_id is not None) if external_entra_id is None else external_entra_id
 
     def _on_consent(resource_name: str, scopes: list[str]) -> None:
         ctx.log(f"Additional consent needed for: {resource_name}")
@@ -636,11 +647,12 @@ def status(ctx: DxsContext) -> None:
             return f"{seconds // 3600} hours"
 
     # Check all cached tokens for each resource.
-    # External-tenant identities must be probed against their own tenant authority;
+    # Foreign-tenant identities must be probed against their own tenant authority;
     # redeeming their refresh token against the default tenant returns invalid_grant.
     settings = get_settings()
-    if active_identity.external_entra_id and active_identity.tenant_id:
-        client = MSALClient.for_tenant(active_identity.tenant_id)
+    foreign_tenant = tenant_authority_for(active_identity)
+    if foreign_tenant:
+        client = MSALClient.for_tenant(foreign_tenant)
     else:
         client = MSALClient()
 
@@ -920,15 +932,15 @@ def consent(
                 )
             )
             raise SystemExit(1)
-        if not org_info.external_entra_id:
+        if not org_needs_tenant_login(org_info):
             ctx.output(
                 single(
                     item={
                         "status": "not_required",
-                        "message": f"Organization '{org}' does not use external authentication",
+                        "message": f"Organization '{org}' authenticates against the Datex home tenant",
                         "organization": org_info.name,
                         "organization_id": org_info.id,
-                        "note": "Admin consent is only required for organizations with external Entra ID tenants",
+                        "note": "Admin consent is only required for organizations with their own Entra tenant",
                     },
                     semantic_key="consent",
                 )
@@ -951,38 +963,49 @@ def consent(
         resolved_domain = org_info.external_entra_id_domain_name
 
     settings = get_settings()
-    base_consent = f"https://login.microsoftonline.com/{resolved_tenant_id}/adminconsent"
-    datex_consent_url = f"{base_consent}?client_id={settings.azure_client_id}"
-    fp_scope = settings.footprint_scope
-    fp_client_id = fp_scope.split("://")[1].split("/")[0] if "://" in fp_scope else None
-    footprint_consent_url = f"{base_consent}?client_id={fp_client_id}" if fp_client_id else None
+    redirect_uri = settings.azure_consent_redirect_uri
+    # Traceability rather than CSRF: nothing in the CLI receives the redirect, so
+    # there is no state to validate against. It lets staff correlate an admin's
+    # "I approved it" with the request they sent.
+    state = f"dxs-{secrets.token_urlsafe(12)}"
+
+    # Only the CLI app needs per-tenant admin consent. The Footprint API app is
+    # consented during customer onboarding in every case, and being a resource app
+    # it has no reply address — its consent URL could only ever fail with
+    # AADSTS500113 before reaching a consent screen.
+    query = urlencode(
+        {
+            "client_id": settings.azure_client_id,
+            "redirect_uri": redirect_uri,
+            "state": state,
+        }
+    )
+    consent_url = f"https://login.microsoftonline.com/{resolved_tenant_id}/adminconsent?{query}"
 
     consent_apps = [
         {
-            "name": "Datex Studio API",
+            "name": "Datex Studio CLI",
             "client_id": settings.azure_client_id,
-            "url": datex_consent_url,
+            "url": consent_url,
         },
     ]
-    if footprint_consent_url and fp_client_id:
-        consent_apps.append(
-            {"name": "Footprint API", "client_id": fp_client_id, "url": footprint_consent_url}
-        )
 
     if open:
         ctx.output(
             single(
                 item={
                     "status": "opening_browser",
-                    "message": f"Opening admin consent pages for {org_name}",
+                    "message": f"Opening the admin consent page for {org_name}",
                     "organization": org_name,
                     "organization_id": org_id,
                     "tenant_id": resolved_tenant_id,
                     "domain": resolved_domain,
+                    "redirect_uri": redirect_uri,
+                    "state": state,
                     "consent_apps": consent_apps,
                     "instructions": (
-                        "A tenant admin must complete the consent flow for BOTH apps. "
-                        "Two browser tabs will open -- approve each one."
+                        "A tenant admin must complete the consent flow. A browser tab "
+                        "will open -- approve it."
                     ),
                 },
                 semantic_key="consent",
@@ -995,15 +1018,18 @@ def consent(
             single(
                 item={
                     "status": "url_generated",
-                    "message": f"Admin consent URLs for {org_name}",
+                    "message": f"Admin consent URL for {org_name}",
                     "organization": org_name,
                     "organization_id": org_id,
                     "tenant_id": resolved_tenant_id,
                     "domain": resolved_domain,
+                    "redirect_uri": redirect_uri,
+                    "state": state,
                     "consent_apps": consent_apps,
                     "instructions": (
-                        "Have a tenant admin open BOTH URLs to grant consent. "
-                        "Both apps must be approved for full CLI functionality."
+                        "Have a tenant admin open this URL and approve it. "
+                        "After approving, the browser lands on a Microsoft page carrying "
+                        "this state value -- that is success, not an error."
                     ),
                 },
                 semantic_key="consent",
@@ -1268,14 +1294,14 @@ def _switch_by_organization(
         )
         raise SystemExit(1)
 
-    # Step 3: Check if external authentication is required
-    if not org_info.external_entra_id:
-        # No external auth needed - provide informative message
+    # Step 3: Check whether this org lives in a tenant of its own
+    if not org_needs_tenant_login(org_info):
+        # Home-tenant org (Datex): the current identity already covers it.
         ctx.output(
             single(
                 item={
                     "status": "no_action_required",
-                    "message": f"Organization '{org_name}' does not require external authentication",
+                    "message": f"Organization '{org_name}' authenticates against the Datex home tenant",
                     "organization": org_info.name,
                     "organization_id": org_info.id,
                     "suggestion": "Your current identity should work with this organization",
@@ -1285,7 +1311,7 @@ def _switch_by_organization(
         )
         return
 
-    # Step 4: External auth required - check if we have identity for that tenant
+    # Step 4: Tenant login required - check if we have identity for that tenant
     if org_info.tenant_id:
         existing_by_tenant = cache.get_identity_by_tenant(org_info.tenant_id)
         if existing_by_tenant and existing_by_tenant.account_username:
@@ -1457,6 +1483,7 @@ def _authenticate_external_tenant(
             on_additional_consent_needed=on_additional_consent_needed,
             tenant_id=org_info.tenant_id,
             domain=org_info.external_entra_id_domain_name,
+            external_entra_id=org_info.external_entra_id,
             organization_id=org_info.id,
             organization_name=org_info.name,
         )
@@ -1553,13 +1580,13 @@ def _login_to_organization(
         )
         raise SystemExit(1)
 
-    # Check if external authentication is required
-    if not org_info.external_entra_id:
+    # Check whether this org lives in a tenant of its own
+    if not org_needs_tenant_login(org_info):
         ctx.output(
             single(
                 item={
                     "status": "no_external_auth",
-                    "message": f"Organization '{org_name}' does not use external authentication",
+                    "message": f"Organization '{org_name}' authenticates against the Datex home tenant",
                     "organization": org_info.name,
                     "organization_id": org_info.id,
                     "suggestion": "Your current identity can access this organization directly",
@@ -1569,7 +1596,7 @@ def _login_to_organization(
         )
         return
 
-    # External auth required - authenticate against external tenant
+    # Tenant login required - authenticate against the org's own tenant
     if not org_info.tenant_id:
         ctx.output_error(
             AuthenticationError(