Add beta branch-aware package workspaces

.github/CODEOWNERS

@@ -5,6 +5,8 @@
 /src/core                                         @celonis/astro
 /src/commands/configuration-management/           @celonis/astro
 /tests/commands/configuration-management/         @celonis/astro
+/src/commands/workspace/                          @celonis/astro
+/tests/commands/workspace/                        @celonis/astro
 /src/commands/t2tc/                               @celonis/astro
 /tests/commands/t2tc/                             @celonis/astro
 /src/commands/profile/                            @celonis/astro

src/commands/workspace/module.ts

@@ -0,0 +1,97 @@
+import { Command, OptionValues } from "commander";
+import { Context } from "../../core/command/cli-context";
+import { Configurator, IModule } from "../../core/command/module-handler";
+import { WorkspaceService } from "./workspace.service";
+
+async function runWorkspaceCommand<T>(action: () => Promise<T> | T): Promise<void> {
+    try {
+        await action();
+    } catch (error) {
+        process.exitCode = 1;
+        throw error;
+    }
+}
+
+class Module extends IModule {
+    public register(context: Context, configurator: Configurator): void {
+        const workspace = configurator.command("workspace").beta().description("Manage a package workspace.");
+
+        workspace
+            .command("clone <projectKey> [directory]")
+            .beta()
+            .description("Clone a package workspace.")
+            .option("--branch <branch>", "Clone a branch")
+            .action(this.clone);
+
+        workspace
+            .command("checkout [branch]")
+            .beta()
+            .description("Select a package branch.")
+            .option("-b, --create <branch>", "Create and select a branch")
+            .option("--discard", "Discard local workspace changes", false)
+            .option("--link-git", "Map the current Git branch", false)
+            .action(this.checkout);
+
+        workspace.command("pull [paths...]").beta().description("Pull remote changes.").action(this.pull);
+
+        workspace.command("status [directory]").beta().description("Show local changes.").action(this.status);
+
+        workspace
+            .command("push [paths...]")
+            .beta()
+            .description("Push local changes.")
+            .option("--asset-type <assetType>", "Asset Type for new files")
+            .action(this.push);
+
+        workspace
+            .command("move <source> <target>")
+            .beta()
+            .description("Move a tracked file to another parent.")
+            .option("--record", "Record an existing move", false)
+            .action(this.move);
+    }
+
+    private async clone(context: Context, command: Command, options: OptionValues): Promise<void> {
+        await runWorkspaceCommand(() =>
+            new WorkspaceService(context).clone(command.args[0], command.args[1], { branch: options.branch })
+        );
+    }
+
+    private async checkout(context: Context, command: Command, options: OptionValues): Promise<void> {
+        await runWorkspaceCommand(async () => {
+            const branch = options.create || command.args[0];
+            if (!branch || (options.create && command.args[0])) {
+                throw new Error("Provide one branch name or use -b <branch>.");
+            }
+            await new WorkspaceService(context).checkout(branch, {
+                create: Boolean(options.create),
+                discard: options.discard,
+                linkGit: options.linkGit,
+            });
+        });
+    }
+
+    private async pull(context: Context, command: Command): Promise<void> {
+        await runWorkspaceCommand(() => new WorkspaceService(context).pull(command.args));
+    }
+
+    private async status(context: Context, command: Command): Promise<void> {
+        await runWorkspaceCommand(() => new WorkspaceService(context).statusWithGit(command.args[0]));
+    }
+
+    private async push(context: Context, command: Command, options: OptionValues): Promise<void> {
+        await runWorkspaceCommand(() =>
+            new WorkspaceService(context).push(command.args, {
+                assetType: options.assetType,
+            })
+        );
+    }
+
+    private async move(context: Context, command: Command, options: OptionValues): Promise<void> {
+        await runWorkspaceCommand(() =>
+            new WorkspaceService(context).move(command.args[0], command.args[1], options.record)
+        );
+    }
+}
+
+export = Module;

src/commands/workspace/workspace-api.ts

@@ -0,0 +1,112 @@
+import { Context } from "../../core/command/cli-context";
+import { GracefulError } from "../../core/utils/logger";
+import { NodeFileWriteResponse, WorkspaceBranch, WorkspaceManifest } from "./workspace.models";
+
+export class WorkspaceApi {
+    constructor(private readonly context: Context) {}
+
+    public async readFile(packageKey: string, filePath: string): Promise<{ body: Buffer; eTag: string }> {
+        const response = await this.context.httpClient.getFileWithHeaders(this.fileUrl(packageKey, filePath));
+        const eTag = response.headers.etag;
+        if (typeof eTag !== "string") {
+            throw new GracefulError(`File response does not contain an ETag: ${filePath}`);
+        }
+        return { body: response.data, eTag };
+    }
+
+    public async manifest(
+        packageKey: string,
+        ifNoneMatch?: string
+    ): Promise<{ manifest?: WorkspaceManifest; eTag: string; notModified: boolean }> {
+        const response = await this.context.httpClient.getFileWithHeaders(
+            `/pacman/api/core/staging/packages/${encodeURIComponent(packageKey)}/files`,
+            ifNoneMatch ? { "If-None-Match": ifNoneMatch } : {},
+            [200, 304]
+        );
+        const eTag = response.headers.etag;
+        if (typeof eTag !== "string" || !eTag) {
+            throw new GracefulError("Workspace manifest response does not contain a package ETag.");
+        }
+        if (response.status === 304) {
+            return { eTag, notModified: true };
+        }
+        try {
+            return {
+                manifest: JSON.parse(response.data.toString("utf-8")) as WorkspaceManifest,
+                eTag,
+                notModified: false,
+            };
+        } catch (error) {
+            const failure = new GracefulError("Workspace manifest response is invalid JSON.");
+            failure.cause = error;
+            throw failure;
+        }
+    }
+
+    public putFile(
+        packageKey: string,
+        filePath: string,
+        assetType: string,
+        body: Buffer,
+        contentType: string,
+        headers: Record<string, string>
+    ): Promise<NodeFileWriteResponse> {
+        return this.context.httpClient.putFile(
+            `${this.fileUrl(packageKey, filePath)}?assetType=${encodeURIComponent(assetType)}`,
+            body,
+            contentType,
+            undefined,
+            headers
+        );
+    }
+
+    public createFolder(packageKey: string, folderPath: string): Promise<NodeFileWriteResponse> {
+        return this.context.httpClient.putFile(
+            this.folderUrl(packageKey, folderPath),
+            Buffer.alloc(0),
+            "application/octet-stream",
+            undefined,
+            { "If-None-Match": "*" }
+        );
+    }
+
+    public moveFile(
+        packageKey: string,
+        sourcePath: string,
+        targetPath: string,
+        eTag: string
+    ): Promise<NodeFileWriteResponse> {
+        return this.context.httpClient.patch(
+            this.fileUrl(packageKey, sourcePath),
+            { targetPath },
+            { "If-Match": eTag }
+        );
+    }
+
+    public deleteFile(packageKey: string, filePath: string, eTag: string): Promise<void> {
+        return this.context.httpClient.delete(this.fileUrl(packageKey, filePath), { "If-Match": eTag });
+    }
+
+    public createBranch(packageKey: string, branchKey: string): Promise<WorkspaceBranch> {
+        return this.context.httpClient.post(`/pacman/api/core/packages/${encodeURIComponent(packageKey)}/branches`, {
+            branchKey,
+            version: "STAGING",
+        });
+    }
+
+    private fileUrl(packageKey: string, filePath: string): string {
+        return this.pathUrl(packageKey, "files", filePath);
+    }
+
+    private folderUrl(packageKey: string, folderPath: string): string {
+        return this.pathUrl(packageKey, "folders", folderPath);
+    }
+
+    private pathUrl(packageKey: string, collection: string, entryPath: string): string {
+        const encodedPath = entryPath
+            .split("/")
+            .map((segment) => encodeURIComponent(segment))
+            .join("/");
+        return `/pacman/api/core/staging/packages/${encodeURIComponent(packageKey)}/${collection}/${encodedPath}`;
+    }
+}