@contrail/cli 3.5.4 → 3.5.5-alpha.5c010ac

package/README.md

@@ -17,7 +17,7 @@ $ npm install -g @contrail/cli
 $ contrail COMMAND
 running command...
 $ contrail (--version)
-@contrail/cli/3.5.4 linux-x64 node-v24.20.0
+@contrail/cli/3.5.5-alpha.5c010ac linux-x64 node-v24.20.0
 $ contrail --help [COMMAND]
 USAGE
   $ contrail COMMAND
@@ -51,6 +51,8 @@ To get instructions on how to set up autocomplete for your shell, run `contrail
 * [`contrail config list`](#contrail-config-list)
 * [`contrail config set`](#contrail-config-set)
 * [`contrail config use [NAME]`](#contrail-config-use-name)
+* [`contrail feature-flags export`](#contrail-feature-flags-export)
+* [`contrail feature-flags import`](#contrail-feature-flags-import)
 * [`contrail file upload FILELOCATION CONTENTTYPE`](#contrail-file-upload-filelocation-contenttype)
 * [`contrail groups export`](#contrail-groups-export)
 * [`contrail groups import GROUPSFILE`](#contrail-groups-import-groupsfile)
@@ -537,6 +539,53 @@ EXAMPLES
   $ contrail config use demo-org
 ```
 
+## `contrail feature-flags export`
+
+Export the enabled feature flags for your Org
+
+```
+USAGE
+  $ contrail feature-flags export [-l error|warn|info|debug] [-e true|false] [-d <value>] [-f]
+
+FLAGS
+  -d, --outDir=<value>             [default: .] The directory to which to export the feature flags. Defaults to the
+                                   current directory
+  -e, --alwaysConfirmEnv=<option>  [default: true] The Environment variables
+                                   <options: true|false>
+  -f, --overwrite                  Replaces any existing export files in outDir
+  -l, --logLevel=<option>          The Log Level
+                                   <options: error|warn|info|debug>
+
+DESCRIPTION
+  Export the enabled feature flags for your Org
+
+EXAMPLES
+  $ contrail feature-flags export
+```
+
+## `contrail feature-flags import`
+
+Upload an extracted set of feature flags
+
+```
+USAGE
+  $ contrail feature-flags import [-l error|warn|info|debug] [-e true|false] [-d <value>]
+
+FLAGS
+  -d, --dir=<value>                [default: .] The directory from which to import the feature flags. Defaults to the
+                                   current directory. The feature flags will be loaded from $dir/feature-flags.yml
+  -e, --alwaysConfirmEnv=<option>  [default: true] The Environment variables
+                                   <options: true|false>
+  -l, --logLevel=<option>          The Log Level
+                                   <options: error|warn|info|debug>
+
+DESCRIPTION
+  Upload an extracted set of feature flags
+
+EXAMPLES
+  $ contrail feature-flags import
+```
+
 ## `contrail file upload FILELOCATION CONTENTTYPE`
 
 Uploads a file to the VibeIQ platform

package/dist/api/feature-flags.d.ts

@@ -0,0 +1,3 @@
+export declare function getFeatureFlags(options?: any): Promise<any[]>;
+export declare function createFeatureFlag(featureName: string): Promise<any>;
+export declare function deleteFeatureFlag(id: string): Promise<any>;

package/dist/api/feature-flags.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deleteFeatureFlag = exports.createFeatureFlag = exports.getFeatureFlags = void 0;
+const sdk_1 = require("@contrail/sdk");
+// a feature flag record exists only for features that are turned ON for the org,
+// and carries no configuration beyond its featureName
+async function getFeatureFlags(options) {
+    return new sdk_1.Entities().get({
+        entityName: 'feature-flag',
+        ...options,
+    });
+}
+exports.getFeatureFlags = getFeatureFlags;
+// the API treats create as an upsert on featureName, so creating an already
+// enabled flag returns the existing record instead of failing
+async function createFeatureFlag(featureName) {
+    return new sdk_1.Entities().create({
+        entityName: 'feature-flag',
+        object: { featureName },
+    });
+}
+exports.createFeatureFlag = createFeatureFlag;
+async function deleteFeatureFlag(id) {
+    return new sdk_1.Entities().delete({
+        entityName: 'feature-flag',
+        id,
+    });
+}
+exports.deleteFeatureFlag = deleteFeatureFlag;

package/dist/api/users.d.ts

@@ -1,2 +1,3 @@
 export declare function getUserOrgs(options?: any): Promise<any[]>;
 export declare function getGroups(options?: any): Promise<any[]>;
+export declare function getCurrentUserWithPlatformRoles(): Promise<any>;

package/dist/api/users.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getGroups = exports.getUserOrgs = void 0;
+exports.getCurrentUserWithPlatformRoles = exports.getGroups = exports.getUserOrgs = void 0;
 const sdk_1 = require("@contrail/sdk");
 async function getUserOrgs(options) {
     return new sdk_1.Entities().get({
@@ -16,3 +16,12 @@ async function getGroups(options) {
     });
 }
 exports.getGroups = getGroups;
+// GET /users/current only populates platformRoles when it is asked for as a relation
+async function getCurrentUserWithPlatformRoles() {
+    return new sdk_1.Entities().get({
+        entityName: 'user',
+        id: 'current',
+        relations: ['platformRoles'],
+    });
+}
+exports.getCurrentUserWithPlatformRoles = getCurrentUserWithPlatformRoles;

package/dist/commands/feature-flags/export.d.ts

@@ -0,0 +1,19 @@
+import { BaseCommand } from '../../basecommand';
+export declare const FEATURE_FLAGS_FILE = "feature-flags.yml";
+export default class ExportFeatureFlags extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        outDir: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        overwrite: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        alwaysConfirmEnv: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        logLevel: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+    };
+    run(): Promise<void>;
+}
+/**
+ * Writes the org's enabled feature flags to $outDir/feature-flags.yml as a list of
+ * `- featureName: X` entries. An org with no flags enabled still gets a file (an empty
+ * list), so the export stays a faithful snapshot of what is turned on.
+ */
+export declare function exportFeatureFlags(outDir: string, overwrite: boolean): Promise<void>;

package/dist/commands/feature-flags/export.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exportFeatureFlags = exports.FEATURE_FLAGS_FILE = void 0;
+const tslib_1 = require("tslib");
+const path = tslib_1.__importStar(require("path"));
+const chalk_1 = tslib_1.__importDefault(require("chalk"));
+const fs_1 = tslib_1.__importDefault(require("fs"));
+const login_1 = require("../../auth/login");
+const core_1 = require("@oclif/core");
+const file_helpers_1 = require("../../helpers/file-helpers");
+const error_helpers_1 = require("../../helpers/error-helpers");
+const feature_flags_1 = require("../../api/feature-flags");
+const basecommand_1 = require("../../basecommand");
+exports.FEATURE_FLAGS_FILE = 'feature-flags.yml';
+class ExportFeatureFlags extends basecommand_1.BaseCommand {
+    static description = 'Export the enabled feature flags for your Org';
+    static examples = [
+        `$ contrail feature-flags export
+`,
+    ];
+    static flags = {
+        ...basecommand_1.BaseCommand.baseFlags,
+        outDir: core_1.Flags.string({
+            char: 'd',
+            description: 'The directory to which to export the feature flags. Defaults to the current directory',
+            required: false,
+            default: '.',
+        }),
+        overwrite: core_1.Flags.boolean({
+            char: 'f',
+            description: 'Replaces any existing export files in outDir',
+            required: false,
+            default: false,
+        }),
+    };
+    async run() {
+        try {
+            await (0, login_1.authUser)();
+            this.log(`${chalk_1.default.blue.bold('START')} Getting Feature Flags.`);
+            this.log(`${chalk_1.default.yellow.bold('FEATURE FLAGS')} Exporting`);
+            await exportFeatureFlags(this.flags.outDir, this.flags.overwrite);
+            this.log(`${chalk_1.default.yellow.bold('FEATURE FLAGS')} Exported`);
+        }
+        catch (e) {
+            this.log(`${chalk_1.default.red.bold('FAIL')} Feature Flags Export Failed. ${(0, error_helpers_1.describeError)(e)}`);
+            process.exitCode = 1;
+            return;
+        }
+        this.log(`${chalk_1.default.green.bold('COMPLETE')} Feature Flags Export Complete.`);
+    }
+}
+exports.default = ExportFeatureFlags;
+/**
+ * Writes the org's enabled feature flags to $outDir/feature-flags.yml as a list of
+ * `- featureName: X` entries. An org with no flags enabled still gets a file (an empty
+ * list), so the export stays a faithful snapshot of what is turned on.
+ */
+async function exportFeatureFlags(outDir, overwrite) {
+    const featureFlags = await (0, feature_flags_1.getFeatureFlags)();
+    const featureNames = [
+        ...new Set((featureFlags ?? []).map((flag) => flag?.featureName).filter(Boolean)),
+    ].sort();
+    fs_1.default.mkdirSync(path.resolve(outDir), { recursive: true });
+    await (0, file_helpers_1.saveData)(featureNames.map((featureName) => ({ featureName })), path.join(outDir, exports.FEATURE_FLAGS_FILE), overwrite);
+}
+exports.exportFeatureFlags = exportFeatureFlags;

package/dist/commands/feature-flags/export.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/feature-flags/export.spec.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const fs_1 = tslib_1.__importDefault(require("fs"));
+const export_1 = tslib_1.__importStar(require("./export"));
+const file_helpers_1 = require("../../helpers/file-helpers");
+const feature_flags_1 = require("../../api/feature-flags");
+const login_1 = require("../../auth/login");
+jest.mock('../../helpers/file-helpers');
+jest.mock('../../api/feature-flags');
+jest.mock('../../auth/login');
+const mocked = (fn) => fn;
+describe('exportFeatureFlags', () => {
+    let mkdirSyncSpy;
+    beforeEach(() => {
+        jest.clearAllMocks();
+        mkdirSyncSpy = jest.spyOn(fs_1.default, 'mkdirSync').mockReturnValue(undefined);
+        mocked(file_helpers_1.saveData).mockResolvedValue(undefined);
+    });
+    afterEach(() => {
+        mkdirSyncSpy.mockRestore();
+    });
+    it('writes the enabled flags sorted, without org specific fields', async () => {
+        mocked(feature_flags_1.getFeatureFlags).mockResolvedValue([
+            { id: '1', orgId: 'org-a', featureName: 'SHOWROOM' },
+            { id: '2', orgId: 'org-a', featureName: 'DEV_TABS' },
+        ]);
+        await (0, export_1.exportFeatureFlags)('out-dir', true);
+        expect(mocked(file_helpers_1.saveData)).toHaveBeenCalledWith([{ featureName: 'DEV_TABS' }, { featureName: 'SHOWROOM' }], 'out-dir/feature-flags.yml', true);
+    });
+    it('still writes a file when no flags are enabled, so the export is a full snapshot', async () => {
+        mocked(feature_flags_1.getFeatureFlags).mockResolvedValue([]);
+        await (0, export_1.exportFeatureFlags)('out-dir', false);
+        expect(mocked(file_helpers_1.saveData)).toHaveBeenCalledWith([], 'out-dir/feature-flags.yml', false);
+    });
+});
+describe('ExportFeatureFlags command', () => {
+    let mkdirSyncSpy;
+    let logs;
+    // oclif's init() parses argv and reads the on-disk config, so drive run() with flags set directly
+    const runCommand = async () => {
+        const command = new export_1.default([], {});
+        command.flags = { outDir: 'out-dir', overwrite: true };
+        jest.spyOn(command, 'log').mockImplementation((message) => logs.push(String(message)));
+        await command.run();
+    };
+    beforeEach(() => {
+        jest.clearAllMocks();
+        logs = [];
+        process.exitCode = undefined;
+        mkdirSyncSpy = jest.spyOn(fs_1.default, 'mkdirSync').mockReturnValue(undefined);
+        mocked(login_1.authUser).mockResolvedValue({});
+        mocked(file_helpers_1.saveData).mockResolvedValue(undefined);
+        mocked(feature_flags_1.getFeatureFlags).mockResolvedValue([]);
+    });
+    afterEach(() => {
+        mkdirSyncSpy.mockRestore();
+        process.exitCode = undefined;
+    });
+    it('leaves the exit code alone on success', async () => {
+        await runCommand();
+        expect(process.exitCode).toBeUndefined();
+        expect(logs.join('\n')).toContain('Feature Flags Export Complete');
+    });
+    const failures = [
+        [
+            'authentication fails',
+            () => {
+                mocked(login_1.authUser).mockRejectedValue(new Error('boom'));
+            },
+        ],
+        [
+            'the API read fails',
+            () => {
+                mocked(feature_flags_1.getFeatureFlags).mockRejectedValue(new Error('boom'));
+            },
+        ],
+        [
+            'the directory cannot be created',
+            () => {
+                mkdirSyncSpy.mockImplementation(() => {
+                    throw new Error('boom');
+                });
+            },
+        ],
+        [
+            'the file write fails',
+            () => {
+                mocked(file_helpers_1.saveData).mockRejectedValue(new Error('boom'));
+            },
+        ],
+    ];
+    it.each(failures)('exits non-zero when %s, so automation does not read it as a success', async (_, fail) => {
+        fail();
+        await runCommand();
+        expect(process.exitCode).toBe(1);
+        const output = logs.join('\n');
+        expect(output).toContain('Feature Flags Export Failed');
+        expect(output).not.toContain('Feature Flags Export Complete');
+    });
+    it('reports the API message rather than a bare "Error"', async () => {
+        // the SDK's ApiError has an undefined message and keeps the body in details
+        mocked(feature_flags_1.getFeatureFlags).mockRejectedValue({
+            details: '{"message":"Forbidden resource","statusCode":403}',
+        });
+        await runCommand();
+        expect(logs.join('\n')).toContain('Forbidden resource');
+    });
+});

package/dist/commands/feature-flags/import.d.ts

@@ -0,0 +1,28 @@
+import { BaseCommand } from '../../basecommand';
+export declare const REQUIRED_PLATFORM_ROLES: string[];
+export default class ImportFeatureFlags extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        dir: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        alwaysConfirmEnv: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        logLevel: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+    };
+    run(): Promise<void>;
+}
+/**
+ * The feature flags API only lets a platform admin/manager create or delete flags, and a
+ * missing role surfaces as a generic 403 partway through the run. Checking up front stops
+ * the command before it half-applies the file.
+ */
+export declare function assertCanManageFeatureFlags(): Promise<void>;
+/**
+ * Makes the target org's enabled feature flags match $dir/feature-flags.yml: enables every
+ * flag in the file and disables any flag the target has that the file does not, the same
+ * way groups import reconciles groups. Feature flags are not editable in place, so there is
+ * no update step.
+ *
+ * Failures are collected and rethrown so an import never reports success while the org is
+ * missing flags.
+ */
+export declare function uploadFeatureFlags(dir: string): Promise<void>;

package/dist/commands/feature-flags/import.js

@@ -0,0 +1,151 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uploadFeatureFlags = exports.assertCanManageFeatureFlags = exports.REQUIRED_PLATFORM_ROLES = void 0;
+const tslib_1 = require("tslib");
+const path = tslib_1.__importStar(require("path"));
+const chalk_1 = tslib_1.__importDefault(require("chalk"));
+const fs_1 = tslib_1.__importDefault(require("fs"));
+const login_1 = require("../../auth/login");
+const core_1 = require("@oclif/core");
+const file_helpers_1 = require("../../helpers/file-helpers");
+const error_helpers_1 = require("../../helpers/error-helpers");
+const feature_flags_1 = require("../../api/feature-flags");
+const users_1 = require("../../api/users");
+const export_1 = require("./export");
+const basecommand_1 = require("../../basecommand");
+const logger_1 = tslib_1.__importDefault(require("../../logger"));
+exports.REQUIRED_PLATFORM_ROLES = ['PLATFORM_ADMIN', 'PLATFORM_MANAGER'];
+class ImportFeatureFlags extends basecommand_1.BaseCommand {
+    static description = 'Upload an extracted set of feature flags';
+    static examples = [
+        `$ contrail feature-flags import
+`,
+    ];
+    static flags = {
+        ...basecommand_1.BaseCommand.baseFlags,
+        dir: core_1.Flags.string({
+            char: 'd',
+            description: `The directory from which to import the feature flags. Defaults to the current directory. The feature flags will be loaded from $dir/${export_1.FEATURE_FLAGS_FILE}`,
+            required: false,
+            default: '.',
+        }),
+    };
+    async run() {
+        try {
+            await (0, login_1.authUser)();
+            await assertCanManageFeatureFlags();
+            this.log(`${chalk_1.default.blue.bold('START')} Uploading Feature Flags.`);
+            this.log(`${chalk_1.default.yellow.bold('FEATURE FLAGS')} Uploading`);
+            await uploadFeatureFlags(this.flags.dir);
+            this.log(`${chalk_1.default.yellow.bold('FEATURE FLAGS')} Uploaded`);
+        }
+        catch (e) {
+            this.log(`${chalk_1.default.red.bold('FAIL')} Feature Flags Upload Failed. ${(0, error_helpers_1.describeError)(e)}`);
+            process.exitCode = 1;
+            return;
+        }
+        this.log(`${chalk_1.default.green.bold('COMPLETE')} Feature Flags Upload Complete.`);
+    }
+}
+exports.default = ImportFeatureFlags;
+/**
+ * The feature flags API only lets a platform admin/manager create or delete flags, and a
+ * missing role surfaces as a generic 403 partway through the run. Checking up front stops
+ * the command before it half-applies the file.
+ */
+async function assertCanManageFeatureFlags() {
+    let platformRoles;
+    try {
+        const currentUser = await (0, users_1.getCurrentUserWithPlatformRoles)();
+        platformRoles = normalizePlatformRoles(currentUser?.platformRoles);
+    }
+    catch (e) {
+        throw new Error(`Could not read your platform roles. ${(0, error_helpers_1.describeError)(e)}`);
+    }
+    if (!platformRoles.some((role) => exports.REQUIRED_PLATFORM_ROLES.includes(role))) {
+        throw new Error(`Importing feature flags requires the ${exports.REQUIRED_PLATFORM_ROLES.join(' or ')} platform role. ` +
+            `Your roles: ${platformRoles.length ? platformRoles.join(', ') : 'none'}.`);
+    }
+}
+exports.assertCanManageFeatureFlags = assertCanManageFeatureFlags;
+/**
+ * Makes the target org's enabled feature flags match $dir/feature-flags.yml: enables every
+ * flag in the file and disables any flag the target has that the file does not, the same
+ * way groups import reconciles groups. Feature flags are not editable in place, so there is
+ * no update step.
+ *
+ * Failures are collected and rethrown so an import never reports success while the org is
+ * missing flags.
+ */
+async function uploadFeatureFlags(dir) {
+    const filePath = path.join(dir, export_1.FEATURE_FLAGS_FILE);
+    if (!fs_1.default.existsSync(filePath)) {
+        logger_1.default.info(`${chalk_1.default.yellow.bold('FEATURE FLAGS')} No feature flags found in ${dir}. Skipping.`);
+        return;
+    }
+    const data = (0, file_helpers_1.loadData)(filePath);
+    if (!Array.isArray(data)) {
+        throw new Error(`${filePath} must contain a YAML list of feature flags`);
+    }
+    const featureNamesToEnable = new Set(data.map(toFeatureName).filter(Boolean));
+    const existingFlags = (await (0, feature_flags_1.getFeatureFlags)()) ?? [];
+    const enabledFeatureNames = new Set(existingFlags.map((flag) => flag?.featureName));
+    const toCreate = [...featureNamesToEnable].filter((name) => !enabledFeatureNames.has(name));
+    const toDelete = existingFlags.filter((flag) => !featureNamesToEnable.has(flag?.featureName));
+    const failures = [];
+    for (const featureName of toCreate) {
+        try {
+            await (0, feature_flags_1.createFeatureFlag)(featureName);
+            logger_1.default.info(`${chalk_1.default.yellow.bold('FEATURE FLAGS')} Enabled ${featureName}`);
+        }
+        catch (e) {
+            failures.push(`could not enable ${featureName}: ${(0, error_helpers_1.describeError)(e)}`);
+        }
+    }
+    const removed = [];
+    for (const flag of toDelete) {
+        try {
+            await (0, feature_flags_1.deleteFeatureFlag)(flag.id);
+            logger_1.default.info(`${chalk_1.default.yellow.bold('FEATURE FLAGS')} Disabled ${flag.featureName}`);
+            removed.push(flag.featureName);
+        }
+        catch (e) {
+            failures.push(`could not disable ${flag.featureName}: ${(0, error_helpers_1.describeError)(e)}`);
+        }
+    }
+    // call out the removals explicitly: they are the only destructive part of the import
+    if (removed.length) {
+        const removedList = removed.sort().join(', ');
+        logger_1.default.info(`${chalk_1.default.yellow.bold('FEATURE FLAGS')} The following ${removed.length} flag(s) were ` +
+            `enabled in this org but not in the source, so they were removed: ${removedList}`);
+    }
+    if (failures.length) {
+        throw new Error(`Failed to apply feature flags. ${failures.join('; ')}`);
+    }
+}
+exports.uploadFeatureFlags = uploadFeatureFlags;
+// the API returns platformRoles as an array, but some contexts carry it as a JSON string
+function normalizePlatformRoles(platformRoles) {
+    if (Array.isArray(platformRoles)) {
+        return platformRoles;
+    }
+    if (typeof platformRoles === 'string') {
+        try {
+            const parsed = JSON.parse(platformRoles);
+            return Array.isArray(parsed) ? parsed : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    return [];
+}
+// entries are exported as `- featureName: X`, but a hand written `- X` is accepted too
+function toFeatureName(entry) {
+    const featureName = typeof entry === 'string' ? entry : entry?.featureName;
+    if (typeof featureName !== 'string' || !featureName.trim()) {
+        logger_1.default.info(`${chalk_1.default.yellow.bold('FEATURE FLAGS')} Skipping entry with no featureName`);
+        return undefined;
+    }
+    return featureName.trim();
+}

package/dist/commands/feature-flags/import.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/feature-flags/import.spec.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const fs_1 = tslib_1.__importDefault(require("fs"));
+const import_1 = require("./import");
+const file_helpers_1 = require("../../helpers/file-helpers");
+const feature_flags_1 = require("../../api/feature-flags");
+const users_1 = require("../../api/users");
+const logger_1 = tslib_1.__importDefault(require("../../logger"));
+jest.mock('../../helpers/file-helpers');
+jest.mock('../../api/feature-flags');
+jest.mock('../../api/users');
+const mocked = (fn) => fn;
+describe('assertCanManageFeatureFlags', () => {
+    beforeEach(() => {
+        jest.clearAllMocks();
+    });
+    it.each(['PLATFORM_ADMIN', 'PLATFORM_MANAGER'])('allows a %s', async (role) => {
+        mocked(users_1.getCurrentUserWithPlatformRoles).mockResolvedValue({ platformRoles: [role] });
+        await expect((0, import_1.assertCanManageFeatureFlags)()).resolves.toBeUndefined();
+    });
+    it('accepts platformRoles serialized as a JSON string', async () => {
+        mocked(users_1.getCurrentUserWithPlatformRoles).mockResolvedValue({
+            platformRoles: '["PLATFORM_MANAGER"]',
+        });
+        await expect((0, import_1.assertCanManageFeatureFlags)()).resolves.toBeUndefined();
+    });
+    it('rejects a user with no platform role', async () => {
+        mocked(users_1.getCurrentUserWithPlatformRoles).mockResolvedValue({ platformRoles: [] });
+        await expect((0, import_1.assertCanManageFeatureFlags)()).rejects.toThrow('requires the PLATFORM_ADMIN or PLATFORM_MANAGER platform role');
+    });
+    it('rejects a user holding only some other platform role', async () => {
+        mocked(users_1.getCurrentUserWithPlatformRoles).mockResolvedValue({
+            platformRoles: ['PLATFORM_USER'],
+        });
+        await expect((0, import_1.assertCanManageFeatureFlags)()).rejects.toThrow('Your roles: PLATFORM_USER.');
+    });
+    it('rejects when the roles could not be read', async () => {
+        mocked(users_1.getCurrentUserWithPlatformRoles).mockRejectedValue(new Error('Forbidden resource'));
+        await expect((0, import_1.assertCanManageFeatureFlags)()).rejects.toThrow('Could not read your platform roles. Forbidden resource');
+    });
+});
+describe('uploadFeatureFlags', () => {
+    let existsSyncSpy;
+    beforeEach(() => {
+        jest.clearAllMocks();
+        existsSyncSpy = jest.spyOn(fs_1.default, 'existsSync').mockReturnValue(true);
+        mocked(feature_flags_1.createFeatureFlag).mockResolvedValue({});
+        mocked(feature_flags_1.deleteFeatureFlag).mockResolvedValue({});
+        mocked(feature_flags_1.getFeatureFlags).mockResolvedValue([]);
+    });
+    afterEach(() => {
+        existsSyncSpy.mockRestore();
+    });
+    it('skips when the export has no feature-flags.yml', async () => {
+        existsSyncSpy.mockReturnValue(false);
+        await (0, import_1.uploadFeatureFlags)('export-dir');
+        expect(mocked(feature_flags_1.getFeatureFlags)).not.toHaveBeenCalled();
+        expect(mocked(feature_flags_1.createFeatureFlag)).not.toHaveBeenCalled();
+    });
+    it('enables every flag from the export that the target org is missing', async () => {
+        mocked(file_helpers_1.loadData).mockReturnValue([{ featureName: 'SHOWROOM' }, { featureName: 'PROMOTE' }]);
+        mocked(feature_flags_1.getFeatureFlags).mockResolvedValue([{ id: '1', featureName: 'SHOWROOM' }]);
+        await (0, import_1.uploadFeatureFlags)('export-dir');
+        expect(mocked(feature_flags_1.createFeatureFlag)).toHaveBeenCalledTimes(1);
+        expect(mocked(feature_flags_1.createFeatureFlag)).toHaveBeenCalledWith('PROMOTE');
+    });
+    it('disables flags the target org has that the export does not, so the orgs match', async () => {
+        mocked(file_helpers_1.loadData).mockReturnValue([{ featureName: 'SHOWROOM' }]);
+        mocked(feature_flags_1.getFeatureFlags).mockResolvedValue([
+            { id: '1', featureName: 'SHOWROOM' },
+            { id: '2', featureName: 'DEV_TABS' },
+        ]);
+        await (0, import_1.uploadFeatureFlags)('export-dir');
+        expect(mocked(feature_flags_1.createFeatureFlag)).not.toHaveBeenCalled();
+        expect(mocked(feature_flags_1.deleteFeatureFlag)).toHaveBeenCalledTimes(1);
+        expect(mocked(feature_flags_1.deleteFeatureFlag)).toHaveBeenCalledWith('2');
+    });
+    it('summarizes what it removed, and why, at the end of the run', async () => {
+        const infoSpy = jest.spyOn(logger_1.default, 'info').mockImplementation(() => undefined);
+        mocked(file_helpers_1.loadData).mockReturnValue([{ featureName: 'SHOWROOM' }]);
+        mocked(feature_flags_1.getFeatureFlags).mockResolvedValue([
+            { id: '1', featureName: 'SHOWROOM' },
+            { id: '2', featureName: 'PROMOTE' },
+            { id: '3', featureName: 'DEV_TABS' },
+        ]);
+        await (0, import_1.uploadFeatureFlags)('export-dir');
+        const summary = infoSpy.mock.calls.map(([message]) => String(message)).at(-1);
+        expect(summary).toContain('2 flag(s) were enabled in this org but not in the source');
+        expect(summary).toContain('DEV_TABS, PROMOTE');
+        infoSpy.mockRestore();
+    });
+    it('does not print a removal summary when nothing was removed', async () => {
+        const infoSpy = jest.spyOn(logger_1.default, 'info').mockImplementation(() => undefined);
+        mocked(file_helpers_1.loadData).mockReturnValue([{ featureName: 'SHOWROOM' }]);
+        mocked(feature_flags_1.getFeatureFlags).mockResolvedValue([{ id: '1', featureName: 'SHOWROOM' }]);
+        await (0, import_1.uploadFeatureFlags)('export-dir');
+        const messages = infoSpy.mock.calls.map(([message]) => String(message));
+        expect(messages.some((message) => message.includes('so they were removed'))).toBe(false);
+        infoSpy.mockRestore();
+    });
+    it('accepts plain feature names and ignores entries with no featureName', async () => {
+        mocked(file_helpers_1.loadData).mockReturnValue(['SHOWROOM', { featureName: '  PROMOTE  ' }, {}, null]);
+        await (0, import_1.uploadFeatureFlags)('export-dir');
+        expect(mocked(feature_flags_1.createFeatureFlag).mock.calls.map(([name]) => name)).toEqual([
+            'SHOWROOM',
+            'PROMOTE',
+        ]);
+    });
+    it('rejects when the file is not a list', async () => {
+        mocked(file_helpers_1.loadData).mockReturnValue({ featureName: 'SHOWROOM' });
+        await expect((0, import_1.uploadFeatureFlags)('export-dir')).rejects.toThrow('must contain a YAML list of feature flags');
+    });
+    it('applies what it can and then rejects, rather than reporting success', async () => {
+        mocked(file_helpers_1.loadData).mockReturnValue([{ featureName: 'SHOWROOM' }, { featureName: 'PROMOTE' }]);
+        mocked(feature_flags_1.createFeatureFlag).mockImplementation(async (featureName) => {
+            if (featureName === 'SHOWROOM') {
+                throw new Error('Forbidden resource');
+            }
+            return {};
+        });
+        await expect((0, import_1.uploadFeatureFlags)('export-dir')).rejects.toThrow('could not enable SHOWROOM: Forbidden resource');
+        expect(mocked(feature_flags_1.createFeatureFlag)).toHaveBeenCalledWith('PROMOTE');
+    });
+});

package/oclif.manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.5.4",
+  "version": "3.5.5-alpha.5c010ac",
   "commands": {
     "app:create": {
       "id": "app:create",
@@ -672,6 +672,116 @@
         }
       }
     },
+    "feature-flags:export": {
+      "id": "feature-flags:export",
+      "description": "Export the enabled feature flags for your Org",
+      "strict": true,
+      "pluginName": "@contrail/cli",
+      "pluginAlias": "@contrail/cli",
+      "pluginType": "core",
+      "aliases": [],
+      "examples": [
+        "$ contrail feature-flags export\n"
+      ],
+      "flags": {
+        "logLevel": {
+          "name": "logLevel",
+          "type": "option",
+          "char": "l",
+          "description": "The Log Level",
+          "required": false,
+          "multiple": false,
+          "options": [
+            "error",
+            "warn",
+            "info",
+            "debug"
+          ]
+        },
+        "alwaysConfirmEnv": {
+          "name": "alwaysConfirmEnv",
+          "type": "option",
+          "char": "e",
+          "description": "The Environment variables",
+          "required": false,
+          "multiple": false,
+          "options": [
+            "true",
+            "false"
+          ],
+          "default": "true"
+        },
+        "outDir": {
+          "name": "outDir",
+          "type": "option",
+          "char": "d",
+          "description": "The directory to which to export the feature flags. Defaults to the current directory",
+          "required": false,
+          "multiple": false,
+          "default": "."
+        },
+        "overwrite": {
+          "name": "overwrite",
+          "type": "boolean",
+          "char": "f",
+          "description": "Replaces any existing export files in outDir",
+          "required": false,
+          "allowNo": false
+        }
+      },
+      "args": {}
+    },
+    "feature-flags:import": {
+      "id": "feature-flags:import",
+      "description": "Upload an extracted set of feature flags",
+      "strict": true,
+      "pluginName": "@contrail/cli",
+      "pluginAlias": "@contrail/cli",
+      "pluginType": "core",
+      "aliases": [],
+      "examples": [
+        "$ contrail feature-flags import\n"
+      ],
+      "flags": {
+        "logLevel": {
+          "name": "logLevel",
+          "type": "option",
+          "char": "l",
+          "description": "The Log Level",
+          "required": false,
+          "multiple": false,
+          "options": [
+            "error",
+            "warn",
+            "info",
+            "debug"
+          ]
+        },
+        "alwaysConfirmEnv": {
+          "name": "alwaysConfirmEnv",
+          "type": "option",
+          "char": "e",
+          "description": "The Environment variables",
+          "required": false,
+          "multiple": false,
+          "options": [
+            "true",
+            "false"
+          ],
+          "default": "true"
+        },
+        "dir": {
+          "name": "dir",
+          "type": "option",
+          "char": "d",
+          "description": "The directory from which to import the feature flags. Defaults to the current directory. The feature flags will be loaded from $dir/feature-flags.yml",
+          "required": false,
+          "multiple": false,
+          "default": "."
+        }
+      },
+      "args": {}
+    },
     "file:upload": {
       "id": "file:upload",
       "description": "Uploads a file to the VibeIQ platform",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrail/cli",
-  "version": "3.5.4",
+  "version": "3.5.5-alpha.5c010ac",
   "description": "VibeIQ's Contrail Platform CLI.",
   "bin": {
     "contrail-cli": "./bin/run",
@@ -116,6 +116,9 @@
       "org-config": {
         "description": "Export and import org-level configuration"
       },
+      "feature-flags": {
+        "description": "Export and import the org's enabled feature flags"
+      },
       "webhooks": {
         "description": "Manage VibeIQ webhooks"
       },