SP-957: move Team-to-Team Copy commands to 't2tc package' group (#370)

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: ZgjimHaziri

.github/CODEOWNERS

@@ -5,6 +5,8 @@
 /src/core                                         @celonis/studio-platform
 /src/commands/configuration-management/           @celonis/astro
 /tests/commands/configuration-management/         @celonis/astro
+/src/commands/t2tc/                               @celonis/studio-platform
+/tests/commands/t2tc/                             @celonis/studio-platform
 /src/commands/profile/                            @celonis/studio-platform
 /src/commands/asset-registry/                     @celonis/astro
 /tests/commands/asset-registry/                   @celonis/astro

docs/user-guide/agentic-development-guide.md

@@ -87,10 +87,10 @@ Or validate during import with the `--validate` flag — note that this runs the
 content-cli config import -d <export_dir> --validate --overwrite
 ```
 
-To also run business-layer rules (PQL parsing, data-model availability, KPI uniqueness, …) and package-settings checks (dependencies, variables, and flavor-specific package settings), run `config validate` against the just-imported staging version:
+To also run business-layer rules (PQL parsing, data-model availability, KPI uniqueness, …) and package-settings checks (dependencies, variables, and flavor-specific package settings), run `config package validate` against the just-imported staging version:
 
 ```bash
-content-cli config validate --packageKey <package-key> --layers SCHEMA BUSINESS PACKAGE_SETTINGS
+content-cli config package validate --packageKey <package-key> --layers SCHEMA BUSINESS PACKAGE_SETTINGS
 ```
 
 If validation returns errors, fix the issues before importing.

docs/user-guide/config-commands.md

@@ -0,0 +1,211 @@
+# Team-to-Team Copy (T2TC) Commands
+
+The `t2tc package` command group moves whole packages — and, optionally, their dependencies and variables — between teams and realms. These commands power the **Team-to-Team Copy** feature: the T2TC backend drives the copy by exporting from a source team and importing into a target team through this CLI.
+
+These commands are a **self-contained, batch-specific set**. `t2tc package export` produces a multi-package **batch archive**, and only the other `t2tc package` commands (`import`, `diff`) understand that archive. It is **not** interchangeable with the package format used by [`config package import`](./config-commands.md#package-commands-config-package) (see [Batch archive vs. package format](#batch-archive-vs-package-format)).
+
+> **Migrating from `config`?** `t2tc package list/export/import/diff` replace the deprecated `config list/export/import/diff` commands. The flags and behaviour are identical — only the command path changed.
+
+| Old (deprecated) | New |
+|---|---|
+| `config list` | `t2tc package list` |
+| `config export` | `t2tc package export` |
+| `config import` | `t2tc package import` |
+| `config diff` | `t2tc package diff` |
+
+## Permissions
+
+`t2tc package` commands run against the Pacman API and are subject to the same permission checks the platform applies in the UI. The required permission depends on the **flavor** of the target package:
+
+| Package flavor | Required permission |
+|---|---|
+| **Studio** (Studio packages and their assets) | **Edit package** permission on the package |
+| **OCDM** (OCDM packages and their assets) | **Edit** (admin) permission on the **data pool** the OCDM package is connected to |
+
+`t2tc package list` is the one exception: instead of failing, it **filters out packages the profile does not have permission to access**. If a package you expect to see is missing from the list, the most likely cause is missing edit permission on the package (Studio) or on its connected data pool (OCDM).
+
+## Batch archive vs. package format
+
+`t2tc package export` produces a multi-package **batch archive** — a top-level `manifest.json`, `variables.json`, `studio.json`, and one nested `<packageKey>_<version>.zip` per package — that is produced and consumed **only** by the `t2tc package` commands. [`config package import`](./config-commands.md#package-commands-config-package), by contrast, works with a plain **package zip** (a `package.json`, an optional `variables.json`, and a `nodes/` folder). The two formats are **not interchangeable**:
+
+- An archive from `t2tc package export` can be imported with `t2tc package import` or inspected with `t2tc package diff` — but **not** with `config package import`.
+- A package zip used by `config package import` **cannot** be imported with `t2tc package import` or diffed with `t2tc package diff`.
+
+Reach for `t2tc package` only for its specific bulk use-case — moving a set of packages together (for example, a migration between teams). To work with a single package, use [`config package import`](./config-commands.md#package-commands-config-package).
+
+## List Packages
+
+Packages can be listed using the following command:
+
+```bash
+content-cli t2tc package list -p <sourceProfile>
+```
+
+The result will be printed in the console containing only the package name and key:
+
+```bash
+info:    Package1 - Key: "package-1"
+```
+
+By using the `--json` option, packages can be exported (saved) in an extended form as a json file in the current working directory.
+
+```bash
+content-cli t2tc package list -p <sourceProfile> --json
+```
+
+The name of the file will be printed in the console with the following format:
+
+```bash
+info:    File downloaded successfully. New filename: 9560f81f-f746-4117-83ee-dd1f614ad624.json
+```
+
+By using the `--flavors` option, you can filter which packages to list. The available flavors are: **STUDIO** and **OCDM**.
+
+To list staging packages instead of deployed packages use the `--staging` option. Please note that this flag is not compatible with the below options.
+
+> For day-to-day staging listing outside the copy workflow, prefer [`config package list`](./config-commands.md#list-packages-config-package-list), which lists staging packages by default.
+
+### List Packages with Dependencies
+
+When using the listing command with the `--json` option, two additional options are available:
+
+- **--withDependencies**: This option will include the dependencies of the packages in the output.
+
+```bash
+content-cli t2tc package list -p <sourceProfile> --withDependencies
+```
+
+- **--packageKeys**: This option allows you to filter the packages by their keys. You can specify multiple package keys separated by spaces.
+
+```bash
+content-cli t2tc package list -p <sourceProfile> --packageKeys key1 ... keyN
+[optional] --withDependencies
+```
+
+## Export Packages
+
+Packages can be exported using the following command:
+
+```bash
+content-cli t2tc package export -p <sourceProfile> --packageKeys key1 ... keyN
+```
+
+The `--keysByVersion` option can be used to export packages by specific version. You can specify multiple packages with version separated by spaces, in the format of 'packageKey.version'.
+The `--withDependencies` option can be used to also export dependencies of the given packages.
+The `--unzip` option can be used to unzip the exported packages into the current working directory.
+
+Depending on the `--unzip` option used, a zip file, or a directory containing the exported packages, will be created in the current working directory containing:
+
+```bash
+exported_package_random_uuid/
+├─ manifest.json
+├─ variable.json
+├─ studio.json
+├─ package_key1-version.zip
+├─ ...
+├─ package_keyN-version.zip
+```
+
+### Git Integration for Export
+
+The following **Git options** are available:
+
+- `--gitProfile <gitProfileName>` – specifies the Git profile to use for exporting directly to a repository.
+  If not specified, the default profile will be used.
+- `--gitBranch <branchName>` – specifies the branch in the Github repository where the export will be pushed.
+
+Example exporting to Git:
+
+```bash
+content-cli t2tc package export -p <sourceProfile> --packageKeys key1 key2 --gitProfile myGitProfile --gitBranch feature-branch
+```
+
+### Export Directory Structure
+
+- manifest.json - File which contains the metadata of the exported packages.
+- studio.json - File which contains the metadata of the exported packages in a format compatible with Studio.
+- variables.json - File which contains the variables of the exported packages.
+- exported packages directories - Directories containing the exported package files, each directory is named after the package key and the version.
+
+Inside each exported package directory, the following files will be present:
+
+- package.json - File which contains the configuration of the exported package.
+- nodes/ - Directory containing the nodes of the exported package.
+
+Inside the nodes directory, a file for each node will be present:
+
+- node_key.json - File which contains the configuration of the exported node.
+
+## Import Packages
+
+Packages can be imported using the following commands, if importing from a zip file:
+
+```bash
+content-cli t2tc package import -p <sourceProfile> -f <relative exported zip file path>
+```
+
+Where `-f` is the short hand operation for `--file`.
+If importing from a directory containing the exported packages, the following command can be used:
+
+```bash
+content-cli t2tc package import -p <sourceProfile> -d <relative exported directory file path>
+```
+
+Where `-d` is the shorthand operation for `--directory`.
+When packages with the same keys exist in the target team, the `--overwrite` option can be used for allowing overwriting of those packages. If the package in target environment contains unpublished changes, they are automatically saved under a new version. This allows you to audit, compare, or roll back to your previous state via the version history if needed.
+
+```bash
+content-cli t2tc package import -p <sourceProfile> -f <file path> --overwrite
+```
+
+### Git Integration for Import
+
+The following **Git options** are available:
+
+- `--gitProfile <gitProfileName>` – specifies the Git profile to use for importing directly from a repository.
+  If not specified, the default profile will be used.
+- `--gitBranch <branchName>` – specifies the branch in the Github repository from which to import.
+
+Example importing from Git:
+
+```bash
+content-cli t2tc package import -p <sourceProfile> --gitProfile myGitProfile --gitBranch feature-branch
+```
+
+Finally, the result of this command will be a list of PostPackageImportData exported as a json file. The file name will be printed with the following message format:
+
+```bash
+info:    Config import report file: 9560f81f-f746-4117-83ee-dd1f614ad624.json
+```
+
+### Validate During Import
+
+Add `--validate` to `t2tc package import` to run validation against each node **before** the import is committed:
+
+```bash
+content-cli t2tc package import -p <sourceProfile> -d <export_dir> --validate --overwrite
+```
+
+`t2tc package import --validate` runs the **SCHEMA** layer only. It does **not** run BUSINESS-layer checks (PQL parsing, data-model availability, KPI uniqueness, etc.) or PACKAGE_SETTINGS checks (package dependencies, variables, and flavor-specific package settings). To run those validations, use [`config package validate`](./config-commands.md#validate-package-configurations-config-package-validate) after the import.
+
+## Diff local zip with deployed version/specific version/staging
+
+To compare local zipped packages with online packages use:
+
+```bash
+content-cli t2tc package diff --file <file>
+```
+
+As with other commands, use `--json` to export the diff to a file.
+To diff against a specific version use the `--baseVersion` parameter. When omitted it will diff against the current deployed version.
+To diff against staging use `--baseVersion STAGING`.
+
+```bash
+content-cli t2tc package diff --file <file> --baseVersion <version>
+```
+
+To diff against the current deployed version and only return whether there are any changes, use the `--hasChanges` flag.
+
+```bash
+content-cli t2tc package diff --file <file> --hasChanges
+```

docs/user-guide/t2tc-commands.md

@@ -13,6 +13,7 @@ nav:
       - Overview: './user-guide/index.md'
       - Studio Commands: './user-guide/studio-commands.md'
       - Config Commands: './user-guide/config-commands.md'
+      - T2TC Commands: './user-guide/t2tc-commands.md'
       - Deployment Commands: './user-guide/deployment-commands.md'
       - Asset Registry Commands: './user-guide/asset-registry-commands.md'
       - Data Pool Commands: './user-guide/data-pool-commands.md'

mkdocs.yaml

@@ -0,0 +1,22 @@
+import { PackageMetadataExportTransport } from "../interfaces/package-export.interfaces";
+import { FatalError } from "../../../core/utils/logger";
+import { HttpClient } from "../../../core/http/http-client";
+import { Context } from "../../../core/command/cli-context";
+
+export class MetadataApi {
+
+    private readonly httpClient: () => HttpClient;
+
+    constructor(context: Context) {
+        this.httpClient = () => context.httpClient;
+    }
+
+    public async exportPackagesMetadata(packageKeys: string[]): Promise<PackageMetadataExportTransport[]> {
+        const queryParams = new URLSearchParams();
+        packageKeys.forEach(packageKey => queryParams.append("packageKeys", packageKey));
+
+        return this.httpClient().get(`/package-manager/api/core/packages/metadata/export?${queryParams.toString()}`).catch(e => {
+            throw new FatalError(`Problem exporting packages metadata: ${e}`);
+        })
+    }
+}

src/commands/configuration-management/api/metadata-api.ts

@@ -0,0 +1,24 @@
+import { PackageExportTransport } from "../interfaces/package-export.interfaces";
+import { FatalError } from "../../../core/utils/logger";
+import { HttpClient } from "../../../core/http/http-client";
+import { Context } from "../../../core/command/cli-context";
+
+export class StagingPackageApi {
+
+    private readonly httpClient: () => HttpClient;
+
+    constructor(context: Context) {
+        this.httpClient = () => context.httpClient;
+    }
+
+    public async findAllStagingPackages(flavors: string[], includeBranches: boolean = false): Promise<PackageExportTransport[]> {
+        const queryParams = new URLSearchParams();
+
+        queryParams.set("includeBranches", includeBranches.toString());
+        flavors.forEach(flavor => queryParams.append("flavors", flavor));
+
+        return this.httpClient().get(`/pacman/api/core/staging/packages/export/list?${queryParams.toString()}`).catch(e => {
+            throw new FatalError(`Problem getting staging packages: ${e}`);
+        });
+    }
+}

src/commands/configuration-management/api/staging-package-api.ts

@@ -0,0 +1,19 @@
+import { PackageKeyAndVersionPair, VariableManifestTransport } from "../interfaces/package-export.interfaces";
+import { FatalError } from "../../../core/utils/logger";
+import { HttpClient } from "../../../core/http/http-client";
+import { Context } from "../../../core/command/cli-context";
+
+export class VariableApi {
+
+    private readonly httpClient: () => HttpClient;
+
+    constructor(context: Context) {
+        this.httpClient = () => context.httpClient;
+    }
+
+    public async findVariablesWithValuesByPackageKeysAndVersion(packagesByKeyAndVersion: PackageKeyAndVersionPair[]): Promise<VariableManifestTransport[]> {
+        return this.httpClient().post("/package-manager/api/core/packages/export/batch/variables-with-assignments", packagesByKeyAndVersion).catch(e => {
+            throw new FatalError(`Problem exporting package variables: ${e}`);
+        })
+    }
+}

src/commands/configuration-management/api/variable-api.ts

@@ -1,42 +1,12 @@
 import { Context } from "../../core/command/cli-context";
-import { BatchImportExportService } from "./batch-import-export.service";
 import { VariableService } from "./variable.service";
-import { DiffService } from "./diff.service";
-import { fileService } from "../../core/utils/file-service";
 
 export class ConfigCommandService {
 
-    private batchImportExportService: BatchImportExportService;
     private variableService: VariableService;
-    private diffService: DiffService;
 
     constructor(context: Context) {
-        this.batchImportExportService = new BatchImportExportService(context);
         this.variableService = new VariableService(context);
-        this.diffService = new DiffService(context);
-    }
-
-    public async listPackages(
-        jsonResponse: boolean,
-        flavors: string[],
-        withDependencies: boolean,
-        packageKeys: string[],
-        keysByVersion: string[],
-        variableValue: string,
-        variableType: string,
-        includeBranches: boolean,
-        staging: boolean): Promise<void> {
-        if (staging) {
-            await this.batchImportExportService.listStagingPackages(flavors ?? [], includeBranches, jsonResponse);
-        } else if (variableValue) {
-            await this.listPackagesByVariableValue(jsonResponse, flavors, variableValue, variableType, includeBranches);
-        } else if (jsonResponse) {
-            await this.batchImportExportService.findAndExportListOfPackages(flavors ?? [], packageKeys ?? [], keysByVersion ?? [], withDependencies, includeBranches);
-        } else if (keysByVersion) {
-            await this.batchImportExportService.listPackagesByKeysWithVersion(keysByVersion, withDependencies);
-        } else {
-            await this.batchImportExportService.listActivePackages(flavors ?? [], includeBranches);
-        }
     }
 
     public async listVariables(
@@ -57,44 +27,4 @@ export class ConfigCommandService {
             await this.variableService.listVariables(keysByVersion, keysByVersionFile);
         }
     }
-
-    public batchExportPackages(packageKeys: string[], packageKeysByVersion: string[], withDependencies: boolean, gitBranch: string, unzip: boolean): Promise<void> {
-        return this.batchImportExportService.batchExportPackages(packageKeys, packageKeysByVersion, withDependencies, gitBranch, unzip);
-    }
-
-    public batchExportPackagesMetadata(packageKeys: string[], jsonResponse: boolean): Promise<void> {
-        return this.batchImportExportService.batchExportPackagesMetadata(packageKeys, jsonResponse);
-    }
-
-    public batchImportPackages(file: string, directory: string, overwrite: boolean, gitBranch: string, performValidation: boolean = false): Promise<void> {
-        if ((directory || file) && gitBranch) {
-            throw new Error("You cannot use both file/directory and gitBranch options at the same time. Only one import source can be defined.");
-        }
-        if (!directory && !file && !gitBranch) {
-            throw new Error("You must provide either a file/directory or a gitBranch option to import packages.");
-        }
-        if (file && directory) {
-            throw new Error("You cannot use both file and directory options at the same time. Only one import source can be defined.");
-        }
-        if (file && fileService.isDirectory(file)) {
-            throw new Error("The file option accepts only zip files.");
-        }
-        if (directory && !fileService.isDirectory(directory)) {
-            throw new Error("The directory option accepts only directories.");
-        }
-        const sourcePath = file ?? directory;
-        return this.batchImportExportService.batchImportPackages(sourcePath, overwrite, gitBranch, performValidation);
-    }
-
-    public diffPackages(file: string, hasChanges: boolean, baseVersion: string, jsonResponse: boolean): Promise<void> {
-        return this.diffService.diffPackages(file, hasChanges, baseVersion, jsonResponse);
-    }
-
-    private async listPackagesByVariableValue(jsonResponse: boolean, flavors: string[], variableValue: string, variableType: string, includeBranches: boolean): Promise<void> {
-        if (jsonResponse) {
-            await this.batchImportExportService.findAndExportListOfActivePackagesByVariableValue(flavors ?? [], variableValue, variableType, includeBranches)
-        } else {
-            await this.batchImportExportService.listActivePackagesByVariableValue(flavors ?? [], variableValue, variableType, includeBranches);
-        }
-    }
 }