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

{datex_studio_cli-0.4.12 → datex_studio_cli-0.4.13}/.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.13}/PKG-INFO

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

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

{datex_studio_cli-0.4.12 → datex_studio_cli-0.4.13}/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,6 +521,7 @@ def register_commands() -> None:
         function,
         init,
         marketplace,
+        ng,
         odata,
         organization,
         proxy,
@@ -520,6 +544,7 @@ 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)
@@ -632,6 +657,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.13}/src/dxs/commands/branch.py

@@ -38,6 +38,7 @@ from dxs.utils import (
 from dxs.utils.errors import ValidationError
 from dxs.utils.responses import list_response, search_response, single
 from dxs.utils.restricted import restrict_in_restricted_mode
+from dxs.utils.versioning import generate_version
 
 
 def enrich_branch_with_status(branch: dict[str, Any]) -> dict[str, Any]:
@@ -1278,8 +1279,8 @@ def create(
 @click.option(
     "--notes",
     "-n",
-    default=None,
-    help="Release notes describing the changes",
+    required=True,
+    help="Release notes describing the changes (required)",
 )
 @click.option(
     "--force",
@@ -1295,7 +1296,7 @@ def publish(
     ctx: DxsContext,
     branch_id: int,
     version: str | None,
-    notes: str | None,
+    notes: str,
     force: bool,
 ) -> None:
     """Publish a branch to the marketplace.
@@ -1310,14 +1311,13 @@ def publish(
     \b
     Options:
         --version, -v  Version string (auto-generated if not provided)
-        --notes, -n    Release notes
+        --notes, -n    Release notes (required)
         --force, -f    Skip validation and confirmation
 
     \b
     Examples:
-        dxs source branch publish 100                     # Auto-generated version
-        dxs source branch publish 100 --version "1.0.0"   # Explicit version
-        dxs source branch publish 100 -v "1.0.0" -n "Initial release"
+        dxs source branch publish 100 -n "Initial release"                 # Auto-generated version
+        dxs source branch publish 100 --version "1.0.0" -n "Initial release"
         dxs source branch publish 100 -v "1.1.0" -n "Bug fixes" --force
     """
     client = ApiClient()
@@ -1342,7 +1342,7 @@ def publish(
 
     # Auto-generate version if not provided (matches Wavelength UI behavior)
     if not version:
-        version = datetime.now().strftime("%Y.%m%d.%H%M")
+        version = generate_version()
         ctx.log(f"Auto-generated version: {version}")
 
     # Warn if not publishing from Main branch
@@ -1379,15 +1379,22 @@ def publish(
 
     ctx.log(f"Publishing branch '{branch_name}' as version {version}...")
 
-    request_data: dict[str, str] = {"version": version}
-    if notes:
-        request_data["releaseNotes"] = notes
+    request_data: dict[str, str] = {"version": version, "releaseNotes": notes}
 
     result = client.post(
         BranchEndpoints.publish(branch_id),
         data=request_data,
     )
 
+    published_version = None
+    if isinstance(result, dict):
+        published_version = {
+            "versionName": result.get("versionName", version),
+            "versionCode": result.get("versionCode"),
+            "marketPlaceApplicationVersionId": result.get("id"),
+            "isLatest": result.get("isLatest"),
+        }
+
     ctx.output(
         single(
             item={
@@ -1396,8 +1403,73 @@ def publish(
                 "branch_name": branch_name,
                 "version": version,
                 "release_notes": notes,
+                "published_version": published_version,
                 "result": result,
             },
             semantic_key="publish_result",
         )
     )
+
+
+@branch.command("commit")
+@click.argument("branch_id", type=int)
+@click.option("--title", "-t", required=True, help="Commit title")
+@click.option("--description", "-d", required=True, help="Commit description (required)")
+@click.option(
+    "--config",
+    "config_refs",
+    multiple=True,
+    help="Reference name of a changed config to commit (repeatable). "
+    "Omit with --all-changes to commit everything modified.",
+)
+@click.option(
+    "--all-changes",
+    is_flag=True,
+    default=False,
+    help="Commit all modified configs on the branch.",
+)
+@pass_context
+@require_auth
+@restrict_in_restricted_mode("commits changes to the Main branch")
+def commit(
+    ctx: DxsContext,
+    branch_id: int,
+    title: str,
+    description: str,
+    config_refs: tuple[str, ...],
+    all_changes: bool,
+) -> None:
+    """Commit (merge) a feature branch into its Main branch.
+
+    \b
+    Examples:
+        dxs source branch commit 3101 --title "bump Module1" -d "Re-pin Module1" --config appConfig
+    """
+    if not config_refs and not all_changes:
+        raise ValidationError(
+            message="Specify --config <ref> (repeatable) or --all-changes.",
+            suggestions=[
+                "dxs source branch commit 3101 -t 'msg' --config appConfig",
+                "dxs source branch commit 3101 -t 'msg' --all-changes",
+            ],
+        )
+
+    client = ApiClient()
+    request_data: dict[str, Any] = {"title": title, "description": description}
+    if not all_changes:
+        request_data["configs"] = list(config_refs)
+
+    ctx.log(f"Committing branch {branch_id}...")
+    result = client.post(SourceControlEndpoints.commit(branch_id), data=request_data)
+
+    ctx.output(
+        single(
+            item={
+                "branch_id": branch_id,
+                "title": title,
+                "new_branch_id": (result or {}).get("newBranchId"),
+                "result": result,
+            },
+            semantic_key="commit_result",
+        )
+    )