SP-1383: gate early-access commands behind feature flag, replace beta

.gitignore

@@ -15,3 +15,6 @@ npm-debug.log
 .idea
 *.iml
 .DS_Store
+
+# Test coverage output
+coverage/

src/commands/deployment/module.ts

@@ -6,11 +6,11 @@ import { DeploymentService } from "./deployment.service";
 class Module extends IModule {
 
     public register(context: Context, configurator: Configurator): void {
-        const deploymentCommand = configurator.command("deployment").beta()
+        const deploymentCommand = configurator.command("deployment").earlyAccess()
             .description("Create deployments, list their history, check active deployments, and retrieve deployables and targets");
 
         deploymentCommand.command("create")
-            .beta()
+            .earlyAccess()
             .description("Create a new deployment")
             .requiredOption("--packageKey <packageKey>", "Identifier of the package to deploy")
             .requiredOption("--packageVersion <packageVersion>", "Version of the package to deploy")
@@ -20,10 +20,10 @@ class Module extends IModule {
             .action(this.createDeployment);
 
         const listCommand = deploymentCommand.command("list")
-            .description("List deployment history, active deployments, deployables or targets").beta();
+            .description("List deployment history, active deployments, deployables or targets").earlyAccess();
 
         listCommand.command("history")
-            .beta()
+            .earlyAccess()
             .description("List deployment history")
             .option("--packageKey <packageKey>", "Filter deployment history by package key")
             .option("--targetId <targetId>", "Filter deployment history by target ID")
@@ -36,7 +36,7 @@ class Module extends IModule {
             .action(this.listDeploymentHistory);
 
         listCommand.command("active")
-            .beta()
+            .earlyAccess()
             .description("Get the active deployment(s) for a given target or package.\n"+
                 "You can use the command to list the active deployment(s) for a specific target or for a specific package.\n" +
                 "The targetIds filter is available only for getting the active deployments for a given package. \n" +
@@ -50,14 +50,14 @@ class Module extends IModule {
             .action(this.listActiveDeployments);
 
         listCommand.command("deployables")
-            .beta()
+            .earlyAccess()
             .description("List all deployables")
             .option("--flavor <flavor>", "Filter deployables by flavor")
             .option("--json", "Return the response as a JSON file")
             .action(this.listDeployables);
 
         listCommand.command("targets")
-            .beta()
+            .earlyAccess()
             .description("List all targets for a given deployable type and package key")
             .requiredOption("--deployableType <deployableType>", "The type of the deployable")
             .requiredOption("--packageKey <packageKey>", "Identifier of the package to list targets for")

src/content-cli.ts

@@ -6,7 +6,6 @@ import { Configurator, IModuleConstructor, ModuleHandler } from "./core/command/
 import { Context } from "./core/command/cli-context";
 import { VersionUtils } from "./core/utils/version";
 import { logger } from "./core/utils/logger";
-import { ContentCLIHelp } from "./core/command/CustomHelp";
 
 /**
  * Celonis Content CLI.
@@ -38,11 +37,6 @@ function addDefaultOptions(program: Command): void {
  */
 export function createProgram(context: Context, opts: CreateProgramOptions = {}): Command {
     const program = new Command();
-    program.configureHelp({
-        formatHelp: (cmd, helper) => new ContentCLIHelp().formatHelp(cmd, helper),
-        subcommandTerm: cmd => new ContentCLIHelp().subcommandTerm(cmd),
-        optionTerm: opt => new ContentCLIHelp().optionTerm(opt),
-    });
     program.version(VersionUtils.getCurrentCliVersion());
     addDefaultOptions(program);
 

src/core/command/module-handler.ts

@@ -1,9 +1,9 @@
 import path = require("path");
 import * as fs from "fs";
-import { Command, CommandOptions, Option, OptionValues } from "commander";
+import { Command, CommandOptions, OptionValues } from "commander";
 import { Context } from "./cli-context";
 import { GracefulError, logger } from "../utils/logger";
-import * as chalk from "chalk";
+import { FeatureFlagService } from "../feature-flag/feature-flag.service";
 
 export abstract class IModule {
     public abstract register(context: Context, commandConfig: Configurator): void;
@@ -186,13 +186,6 @@ export class CommandConfig {
         return this;
     }
 
-    public betaOption(flags: string, description?: string, defaultValue?: string | boolean | string[]): CommandConfig {
-        const option = new Option(flags, description).default(defaultValue);
-        (option as any).isBeta = true;
-        this.cmd.addOption(option);
-        return this;
-    }
-
     public requiredOption(flags: string, description?: string, defaultValue?: string | boolean | string[]): CommandConfig {
         this.cmd.requiredOption(flags, description, defaultValue);
         return this;
@@ -203,17 +196,24 @@ export class CommandConfig {
         return this;
     }
 
-    public beta(): CommandConfig {
-        (this.cmd as any).isBeta = true;
+    /**
+     * Marks a command as early access (internal, not shown in help). With a feature
+     * key, the command is gated at run time on that backend flag.
+     */
+    public earlyAccess(featureKey?: string): this {
+        const command = this.cmd as any
+        command.isEarlyAccess = true;
+        if (featureKey) {
+            command.earlyAccessFeatureKey = featureKey;
+        }
         return this;
     }
 
     public action(handler: CommandHandler): void {
         this.cmd.action(async (): Promise<void> => {
             try {
-                this.printBetaNoticeIfBetaCommand();
-                this.printBetaNoticeIfBetaOptions();
                 this.printDeprecationNoticeIfDeprecated();
+                await this.checkEarlyAccessFeatureFlag();
                 await handler(this.ctx, this.cmd, this.cmd.optsWithGlobals());
             } catch (error) {
                 if (error instanceof GracefulError) {
@@ -232,22 +232,30 @@ export class CommandConfig {
         }
     }
 
-    private printBetaNoticeIfBetaCommand(): void {
-        if ((this.cmd as any).isBeta) {
-            logger.info(chalk.yellow("This command is in beta and may change in future releases."));
-        }
-    }
-
-    private printBetaNoticeIfBetaOptions(): void {
-        if ((this.cmd as any).isBeta) {
+    /** Blocks an early-access command (one with a feature key) unless its flag is enabled for the team. */
+    private async checkEarlyAccessFeatureFlag(): Promise<void> {
+        const featureKey = (this.cmd as any).earlyAccessFeatureKey;
+        if (!featureKey) {
             return;
         }
-        const providedOptions = this.cmd.optsWithGlobals();
-        for (const option of this.cmd.options) {
-            const optionName = option.attributeName();
-            if ((option as any).isBeta && Object.hasOwn(providedOptions, optionName)) {
-                logger.info(chalk.yellow(`The option '${option.long}' is in beta and may change in future releases.`));
+
+        let enabled: boolean;
+        try {
+            enabled = await new FeatureFlagService(this.ctx).isEnabled(featureKey);
+        } catch (error) {
+            // No profile: let the standard "no profile provided" error surface instead of masking it.
+            if (!this.ctx.profile) {
+                throw error;
             }
+            throw new GracefulError(
+                `Could not verify whether '${this.cmd.name()}' is enabled for your team. Please try again later or contact support.`
+            );
+        }
+
+        if (!enabled) {
+            throw new GracefulError(
+                `'${this.cmd.name()}' is not enabled for your team. Contact support to request access.`
+            );
         }
     }
 }

src/core/feature-flag/early-access-features.ts

@@ -0,0 +1,6 @@
+/** Backend feature-flag keys for early-access commands (passed to `earlyAccess(...)`). */
+export const EarlyAccessFeature = {
+    BRANCHING: "pacman.branching",
+} as const;
+
+export type EarlyAccessFeatureKey = (typeof EarlyAccessFeature)[keyof typeof EarlyAccessFeature];

src/core/feature-flag/feature-flag.service.ts

@@ -0,0 +1,25 @@
+import { Context } from "../command/cli-context";
+import { HttpClient } from "../http/http-client";
+
+interface TeamFeature {
+    key: string;
+}
+
+/**
+ * Checks whether a backend feature flag is enabled for the current team via
+ * `GET /api/team/features` — a flag is enabled when its key is in the returned list.
+ */
+export class FeatureFlagService {
+    private static readonly TEAM_FEATURES_URL = "/api/team/features";
+
+    private readonly httpClient: () => HttpClient;
+
+    constructor(context: Context) {
+        this.httpClient = () => context.httpClient;
+    }
+
+    public async isEnabled(featureKey: string): Promise<boolean> {
+        const features: TeamFeature[] = await this.httpClient().get(FeatureFlagService.TEAM_FEATURES_URL);
+        return Array.isArray(features) && features.some(feature => feature?.key === featureKey);
+    }
+}

tests/commands/action-flows/module.spec.ts

@@ -0,0 +1,19 @@
+import Module = require("../../../src/commands/action-flows/module");
+import { testContext } from "../../utls/test-context";
+import { createMockConfigurator } from "../../utls/configurator-mock";
+
+describe("Action Flows Module", () => {
+    describe("register", () => {
+        it("registers the action-flows command groups without throwing", () => {
+            const mockConfigurator = createMockConfigurator();
+
+            expect(() => new Module().register(testContext, mockConfigurator)).not.toThrow();
+
+            expect(mockConfigurator.command).toHaveBeenCalledWith("analyze");
+            expect(mockConfigurator.command).toHaveBeenCalledWith("export");
+            expect(mockConfigurator.command).toHaveBeenCalledWith("import");
+            expect(mockConfigurator.command).toHaveBeenCalledWith("pull");
+            expect(mockConfigurator.command).toHaveBeenCalledWith("push");
+        });
+    });
+});

tests/commands/data-pipeline/module.spec.ts

@@ -0,0 +1,23 @@
+import Module = require("../../../src/commands/data-pipeline/module");
+import { testContext } from "../../utls/test-context";
+import { createMockConfigurator } from "../../utls/configurator-mock";
+
+describe("Data Pipeline Module", () => {
+    describe("register", () => {
+        it("registers the data-pool and connection command groups without throwing", () => {
+            const mockConfigurator = createMockConfigurator();
+
+            expect(() => new Module().register(testContext, mockConfigurator)).not.toThrow();
+
+            // data-pool commands
+            expect(mockConfigurator.command).toHaveBeenCalledWith("export");
+            expect(mockConfigurator.command).toHaveBeenCalledWith("import");
+            expect(mockConfigurator.command).toHaveBeenCalledWith("list");
+            expect(mockConfigurator.command).toHaveBeenCalledWith("pull");
+            expect(mockConfigurator.command).toHaveBeenCalledWith("push");
+            // connection commands
+            expect(mockConfigurator.command).toHaveBeenCalledWith("get");
+            expect(mockConfigurator.command).toHaveBeenCalledWith("set");
+        });
+    });
+});

tests/commands/deployment/module.spec.ts

@@ -0,0 +1,44 @@
+import Module = require("../../../src/commands/deployment/module");
+import { testContext } from "../../utls/test-context";
+import { createMockConfigurator } from "../../utls/configurator-mock";
+
+describe("Deployment Module", () => {
+    describe("register", () => {
+        it("registers the deployment command groups without throwing", () => {
+            const mockConfigurator = createMockConfigurator();
+
+            expect(() => new Module().register(testContext, mockConfigurator)).not.toThrow();
+
+            expect(mockConfigurator.command).toHaveBeenCalledWith("deployment");
+            expect(mockConfigurator.command).toHaveBeenCalledWith("create");
+            expect(mockConfigurator.command).toHaveBeenCalledWith("list");
+            expect(mockConfigurator.command).toHaveBeenCalledWith("history");
+            expect(mockConfigurator.command).toHaveBeenCalledWith("active");
+            expect(mockConfigurator.command).toHaveBeenCalledWith("deployables");
+            expect(mockConfigurator.command).toHaveBeenCalledWith("targets");
+        });
+
+        it("marks every deployment command as early access", () => {
+            const mockConfigurator = createMockConfigurator();
+
+            new Module().register(testContext, mockConfigurator);
+
+            // deployment, create, list, history, active, deployables, targets
+            const expectedEarlyAccessCommands = 7;
+            expect(mockConfigurator.earlyAccess).toHaveBeenCalledTimes(expectedEarlyAccessCommands);
+        });
+
+        it("wires an action handler for every leaf subcommand", () => {
+            const mockConfigurator = createMockConfigurator();
+
+            new Module().register(testContext, mockConfigurator);
+
+            // create, history, active, deployables, targets
+            const expectedLeafCommands = 5;
+            expect(mockConfigurator.action).toHaveBeenCalledTimes(expectedLeafCommands);
+            for (const call of mockConfigurator.action.mock.calls) {
+                expect(typeof call[0]).toBe("function");
+            }
+        });
+    });
+});