@signageos/cli 2.8.0 → 3.0.0-rc.0

package/dist/Applet/Upload/appletUploadFacade.js

@@ -60,9 +60,17 @@ function updateSingleFileApplet(parameters) {
     return __awaiter(this, void 0, void 0, function* () {
         const { restApi, applet } = parameters;
         const appletBinary = fs.createReadStream(applet.binaryFilePath, { encoding: 'utf8' });
-        yield restApi.applet.version.update(applet.uid, applet.version, {
+        yield restApi.applet.version
+            .update(applet.uid, applet.version, {
             binary: appletBinary,
             frontAppletVersion: applet.frontAppletVersion,
+        })
+            .catch((error) => {
+            if (error instanceof Error) {
+                throw new Error(`Failed to update applet version "${applet.version}" with binary file "${applet.binaryFilePath}": ${error.message}\n` +
+                    `Please check that the file exists, is readable, and that you have permissions to update the applet.`);
+            }
+            throw error;
         });
     });
 }
@@ -91,40 +99,44 @@ const updateMultiFileApplet = (parameters) => __awaiter(void 0, void 0, void 0,
         }
         else {
             changedFilesCounter++;
-            (0, log_1.log)('info', chalk_1.default.yellow(` Uploading ${fileAbsolutePath}`));
         }
         if (progressBar) {
-            progressBar.init({ size: fileSize, name: fileRelativePath });
+            progressBar.init({ size: fileSize, name: fileRelativePosixPath });
         }
         const fileStream = fs.createReadStream(fileAbsolutePath);
         fileStream.pause();
         fileStream.on('data', (chunk) => {
             if (progressBar) {
-                progressBar.update({ add: chunk.length });
+                progressBar.update({ add: chunk.length, name: fileRelativePosixPath });
             }
         });
-        try {
-            // update file is just alias to create file (both are idempotent)
-            yield restApi.applet.version.file.update(applet.uid, applet.version, fileRelativePosixPath, {
-                content: fileStream,
-                hash: fileHash,
-                size: fileSize,
-                type: fileType,
-            }, { build: false });
-        }
-        catch (error) {
+        // update file is just alias to create file (both are idempotent)
+        yield restApi.applet.version.file
+            .update(applet.uid, applet.version, fileRelativePosixPath, {
+            content: fileStream,
+            hash: fileHash,
+            size: fileSize,
+            type: fileType,
+        }, { build: false })
+            .catch((error) => {
             if (fileSize === 0) {
                 throw new Error(`Empty files are temporarily disallowed ${fileAbsolutePath}`);
             }
+            // Enhance error message with more context
+            if (error instanceof Error) {
+                const enhancedError = new Error(`Failed to upload file "${fileAbsolutePath}": ${error.message}\n` + `File details: Size=${fileSize} bytes, Type=${fileType}`);
+                // Preserve the original stack trace if available
+                if (error.stack) {
+                    enhancedError.stack = error.stack;
+                }
+                throw enhancedError;
+            }
             throw error;
-        }
+        });
     }
     for (const fileRelativePath in currentAppletFiles) {
         if (Object.prototype.hasOwnProperty.call(currentAppletFiles, fileRelativePath)) {
-            try {
-                yield restApi.applet.version.file.remove(applet.uid, applet.version, fileRelativePath, { build: false });
-            }
-            catch (error) {
+            yield restApi.applet.version.file.remove(applet.uid, applet.version, fileRelativePath, { build: false }).catch((error) => {
                 if (error instanceof NotFoundError_1.default) {
                     /*
                      * This means that the file we are trying to remove somehow already got removed.
@@ -134,9 +146,17 @@ const updateMultiFileApplet = (parameters) => __awaiter(void 0, void 0, void 0,
                     Debug(`remove old file ${fileRelativePath} failed`);
                 }
                 else {
+                    // Add more context to file removal errors
+                    if (error instanceof Error) {
+                        const enhancedError = new Error(`Failed to remove obsolete file "${fileRelativePath}": ${error.message}`);
+                        if (error.stack) {
+                            enhancedError.stack = error.stack;
+                        }
+                        throw enhancedError;
+                    }
                     throw error;
                 }
-            }
+            });
             changedFilesCounter++;
         }
     }
@@ -144,8 +164,16 @@ const updateMultiFileApplet = (parameters) => __awaiter(void 0, void 0, void 0,
     const appletEntryFilePosixPath = path.posix.normalize(applet.entryFilePath.replace(/\\/g, '/'));
     if (changedFilesCounter > 0 || appletVersion.entryFile !== appletEntryFilePosixPath) {
         // The update applet version has to be the last after upload all files to trigger applet version build
-        yield restApi.applet.version.update(applet.uid, applet.version, {
+        yield restApi.applet.version
+            .update(applet.uid, applet.version, {
             entryFile: appletEntryFilePosixPath,
+        })
+            .catch((error) => {
+            if (error instanceof Error) {
+                throw new Error(`Failed to update applet version with entry file "${appletEntryFilePosixPath}": ${error.message}\n` +
+                    `This usually happens when the entry file is missing, has errors, or the applet version cannot be built.`);
+            }
+            throw error;
         });
     }
     if (progressBar) {
@@ -159,10 +187,18 @@ exports.updateMultiFileApplet = updateMultiFileApplet;
 const createSingleFileApplet = (parameters) => __awaiter(void 0, void 0, void 0, function* () {
     const { restApi, applet } = parameters;
     const appletBinary = fs.createReadStream(applet.binaryFilePath, { encoding: 'utf8' });
-    yield restApi.applet.version.create(applet.uid, {
+    yield restApi.applet.version
+        .create(applet.uid, {
         binary: appletBinary,
         version: applet.version,
         frontAppletVersion: applet.frontAppletVersion,
+    })
+        .catch((error) => {
+        if (error instanceof Error) {
+            throw new Error(`Failed to create applet version "${applet.version}" with binary file "${applet.binaryFilePath}": ${error.message}\n` +
+                `Please check that the file exists, is readable, and that you have permissions to create applet versions.`);
+        }
+        throw error;
     });
 });
 exports.createSingleFileApplet = createSingleFileApplet;
@@ -170,39 +206,71 @@ const createMultiFileFileApplet = (parameters) => __awaiter(void 0, void 0, void
     const { restApi, applet, progressBar } = parameters;
     const appletEntryFilePosixPath = path.posix.normalize(applet.entryFilePath.replace(/\\/g, '/'));
     try {
-        yield restApi.applet.version.create(applet.uid, {
+        yield restApi.applet.version
+            .create(applet.uid, {
             version: applet.version,
             entryFile: appletEntryFilePosixPath,
-        });
-        yield Promise.all(applet.files.map((fileAbsolutePath) => __awaiter(void 0, void 0, void 0, function* () {
-            const fileRelativePath = (0, appletUploadFacadeHelper_1.getAppletFileRelativePath)(fileAbsolutePath, applet.directoryPath);
-            const fileHash = yield (0, fileSystem_1.getFileMD5Checksum)(fileAbsolutePath);
-            const fileType = yield (0, fileSystem_1.getFileType)(fileAbsolutePath);
-            const fileSize = (yield fs.stat(fileAbsolutePath)).size;
-            if (fileSize === 0) {
-                throw new Error(`Empty files are temporarily disallowed ${fileAbsolutePath}`);
-            }
-            if (progressBar) {
-                progressBar.init({ size: fileSize, name: fileRelativePath });
+        })
+            .catch((error) => {
+            if (error instanceof Error) {
+                throw new Error(`Failed to create applet version "${applet.version}": ${error.message}\n` +
+                    `Please check that you have permissions to create applet versions and that the version is valid.`);
             }
-            const fileStream = fs.createReadStream(fileAbsolutePath);
-            fileStream.pause();
-            fileStream.on('data', (chunk) => {
+            throw error;
+        });
+        // Process files sequentially to avoid concurrent progress bar issues
+        for (const fileAbsolutePath of applet.files) {
+            try {
+                const fileRelativePath = (0, appletUploadFacadeHelper_1.getAppletFileRelativePath)(fileAbsolutePath, applet.directoryPath);
+                const fileHash = yield (0, fileSystem_1.getFileMD5Checksum)(fileAbsolutePath);
+                const fileType = yield (0, fileSystem_1.getFileType)(fileAbsolutePath);
+                const fileSize = (yield fs.stat(fileAbsolutePath)).size;
+                if (fileSize === 0) {
+                    (0, log_1.log)('info', chalk_1.default.yellow(`Skipping empty file ${fileAbsolutePath}`));
+                    continue;
+                }
+                const filePosixPath = path.posix.normalize(fileRelativePath.replace(/\\/g, '/'));
                 if (progressBar) {
-                    progressBar.update({ add: chunk.length });
+                    progressBar.init({ size: fileSize, name: filePosixPath });
                 }
-            });
-            const filePosixPath = path.posix.normalize(fileRelativePath.replace(/\\/g, '/'));
-            (0, log_1.log)('info', chalk_1.default.yellow(` Uploading ${fileAbsolutePath}`));
-            return restApi.applet.version.file.create(applet.uid, applet.version, {
-                name: path.basename(filePosixPath),
-                path: filePosixPath,
-                type: fileType,
-                hash: fileHash,
-                content: fileStream,
-                size: fileSize,
-            }, { build: false });
-        })));
+                const fileStream = fs.createReadStream(fileAbsolutePath);
+                fileStream.pause();
+                fileStream.on('data', (chunk) => {
+                    if (progressBar) {
+                        progressBar.update({ add: chunk.length, name: filePosixPath });
+                    }
+                });
+                yield restApi.applet.version.file
+                    .create(applet.uid, applet.version, {
+                    name: path.basename(filePosixPath),
+                    path: filePosixPath,
+                    type: fileType,
+                    hash: fileHash,
+                    content: fileStream,
+                    size: fileSize,
+                }, { build: false })
+                    .catch((error) => {
+                    if (error instanceof Error) {
+                        throw new Error(`Failed to upload file "${fileAbsolutePath}": ${error.message}\n` +
+                            `File details: Size=${fileSize} bytes, Type=${fileType}`);
+                    }
+                    throw error;
+                });
+            }
+            catch (error) {
+                if (error instanceof Error) {
+                    if (fileAbsolutePath) {
+                        const enhancedError = new Error(`Failed to upload file "${fileAbsolutePath}": ${error.message}`);
+                        // Preserve the original stack trace if available
+                        if (error.stack) {
+                            enhancedError.stack = error.stack;
+                        }
+                        throw enhancedError;
+                    }
+                }
+                throw error;
+            }
+        }
     }
     finally {
         if (progressBar) {
@@ -210,8 +278,12 @@ const createMultiFileFileApplet = (parameters) => __awaiter(void 0, void 0, void
         }
     }
     // The extra update applet version which has to be after upload all files to trigger applet version build
-    yield restApi.applet.version.update(applet.uid, applet.version, {
-        entryFile: appletEntryFilePosixPath,
+    yield restApi.applet.version.update(applet.uid, applet.version, { entryFile: appletEntryFilePosixPath }).catch((error) => {
+        if (error instanceof Error) {
+            throw new Error(`Failed to finalize applet version with entry file "${appletEntryFilePosixPath}": ${error.message}\n` +
+                `This usually happens when there were issues with one or more uploaded files or when building the applet.`);
+        }
+        throw error;
     });
 });
 exports.createMultiFileFileApplet = createMultiFileFileApplet;

package/dist/Applet/Upload/appletUploadFacadeHelper.d.ts

@@ -2,5 +2,5 @@ import RestApi from '@signageos/sdk/dist/RestApi/RestApi';
 import IAppletVersionFile from '@signageos/sdk/dist/RestApi/Applet/Version/File/IAppletVersionFile';
 export declare function getAppletFileRelativePath(fileAbsolutePath: string, directoryAbsolutePath: string): string;
 export declare function getAppletFilesDictionary(restApi: RestApi, appletUid: string, appletVersion: string): Promise<{
-    [fileRelativePath: string]: IAppletVersionFile;
+    [path: string]: IAppletVersionFile;
 }>;

package/dist/Applet/Upload/appletUploadFacadeHelper.js

@@ -45,6 +45,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getAppletFileRelativePath = getAppletFileRelativePath;
 exports.getAppletFilesDictionary = getAppletFilesDictionary;
 const path = __importStar(require("path"));
+const paginationHelper_1 = require("../../helper/paginationHelper");
 function getAppletFileRelativePath(fileAbsolutePath, directoryAbsolutePath) {
     const directoryAbsolutePathNormalized = path.normalize(directoryAbsolutePath);
     const fileAbsolutePathNormalized = path.normalize(fileAbsolutePath);
@@ -66,10 +67,10 @@ function getAppletFileRelativePath(fileAbsolutePath, directoryAbsolutePath) {
 function getAppletFilesDictionary(restApi, appletUid, appletVersion) {
     return __awaiter(this, void 0, void 0, function* () {
         const filesDictionary = {};
-        const currentAppletFiles = yield restApi.applet.version.file.list(appletUid, appletVersion);
-        currentAppletFiles.forEach((file) => {
+        const files = yield (0, paginationHelper_1.getAllPages)(yield restApi.applet.version.file.list(appletUid, appletVersion));
+        for (const file of files) {
             filesDictionary[file.path] = file;
-        });
+        }
         return filesDictionary;
     });
 }

package/dist/Applet/appletErrors.d.ts

@@ -1,3 +1,6 @@
 export declare class AppletDoesNotExistError extends Error {
     constructor(message: string);
 }
+export declare class AppletSelectionCancelledError extends Error {
+    constructor(message?: string);
+}

package/dist/Applet/appletErrors.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AppletDoesNotExistError = void 0;
+exports.AppletSelectionCancelledError = exports.AppletDoesNotExistError = void 0;
 class AppletDoesNotExistError extends Error {
     constructor(message) {
         super(message);
@@ -8,3 +8,10 @@ class AppletDoesNotExistError extends Error {
     }
 }
 exports.AppletDoesNotExistError = AppletDoesNotExistError;
+class AppletSelectionCancelledError extends Error {
+    constructor(message = 'Applet selection was cancelled') {
+        super(message);
+        Object.setPrototypeOf(this, AppletSelectionCancelledError.prototype);
+    }
+}
+exports.AppletSelectionCancelledError = AppletSelectionCancelledError;

package/dist/Applet/appletFacade.js

@@ -56,6 +56,8 @@ const chalk_1 = __importDefault(require("chalk"));
 const parameters_1 = require("../parameters");
 const packageConfig_1 = require("@signageos/sdk/dist/FileSystem/packageConfig");
 const appletErrors_1 = require("./appletErrors");
+const helper_1 = require("../helper");
+const paginationHelper_1 = require("../helper/paginationHelper");
 exports.APPLET_UID_OPTION = { name: 'applet-uid', type: String, description: 'Applet UID' };
 function getApplet(directoryPath) {
     return __awaiter(this, void 0, void 0, function* () {
@@ -96,7 +98,8 @@ function getAppletUid(restApi_1, options_1) {
         const currentApplet = yield getApplet(currentDirectory);
         let appletUid = options['applet-uid'] || currentApplet.uid;
         if (!appletUid) {
-            const applets = yield restApi.applet.list();
+            // Fetch all pages to ensure we don't miss any applets
+            const applets = yield (0, paginationHelper_1.getAllPages)(yield restApi.applet.list());
             const candidatesOfApplets = applets.filter((applet) => applet.name === currentApplet.name);
             if (candidatesOfApplets.length === 0) {
                 appletUid = undefined;
@@ -114,7 +117,11 @@ function getAppletUid(restApi_1, options_1) {
                             title: `${applet.name} (${applet.uid})`,
                             value: applet.uid,
                         })),
+                        suggest: helper_1.autocompleteSuggest,
                     });
+                    if (!response.appletUid) {
+                        throw new appletErrors_1.AppletSelectionCancelledError();
+                    }
                     appletUid = response.appletUid;
                 }
             }
@@ -132,7 +139,7 @@ function getAppletVersionFromApi(restApi_1, appletUid_1) {
     return __awaiter(this, arguments, void 0, function* (restApi, appletUid, skipConfirmation = false) {
         var _a;
         let appletVersion;
-        const appletVersions = yield restApi.applet.version.list(appletUid);
+        const appletVersions = yield (0, paginationHelper_1.getAllPages)(yield restApi.applet.version.list(appletUid));
         if (appletVersions.length === 1 && ((_a = appletVersions[0]) === null || _a === void 0 ? void 0 : _a.version)) {
             appletVersion = appletVersions[0].version;
         }
@@ -148,7 +155,11 @@ function getAppletVersionFromApi(restApi_1, appletUid_1) {
                     title: applet.version,
                     value: applet.version,
                 })),
+                suggest: helper_1.autocompleteSuggest,
             });
+            if (!response.appletVersion) {
+                throw new Error('Applet version selection was cancelled');
+            }
             appletVersion = response.appletVersion;
         }
         return appletVersion;

package/dist/Applet/appletValidation.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Checks if the given directory appears to be a valid signageOS applet directory.
+ *
+ * A valid applet has @signageos/front-applet as a dependency.
+ * This is the definitive marker that distinguishes applets from other projects.
+ *
+ * @param directoryPath - The directory path to validate
+ * @returns true if the directory appears to be a valid applet, false otherwise
+ */
+export declare function isValidAppletDirectory(directoryPath: string): Promise<boolean>;
+/**
+ * Validates that the directory is a valid applet directory and throws an error if not.
+ *
+ * @param directoryPath - The directory path to validate
+ * @throws {Error} If the directory is not a valid applet directory
+ */
+export declare function validateAppletDirectory(directoryPath: string): Promise<void>;

package/dist/Applet/appletValidation.js

@@ -0,0 +1,62 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidAppletDirectory = isValidAppletDirectory;
+exports.validateAppletDirectory = validateAppletDirectory;
+const packageConfig_1 = require("@signageos/sdk/dist/FileSystem/packageConfig");
+const chalk_1 = __importDefault(require("chalk"));
+/**
+ * Checks if the given directory appears to be a valid signageOS applet directory.
+ *
+ * A valid applet has @signageos/front-applet as a dependency.
+ * This is the definitive marker that distinguishes applets from other projects.
+ *
+ * @param directoryPath - The directory path to validate
+ * @returns true if the directory appears to be a valid applet, false otherwise
+ */
+function isValidAppletDirectory(directoryPath) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        try {
+            const packageJSONObject = yield (0, packageConfig_1.loadPackage)(directoryPath);
+            if (!packageJSONObject) {
+                return false;
+            }
+            // Check for @signageos/front-applet dependency
+            // If package has it, it's an applet
+            const hasFrontApplet = !!(((_a = packageJSONObject.dependencies) === null || _a === void 0 ? void 0 : _a['@signageos/front-applet']) || ((_b = packageJSONObject.devDependencies) === null || _b === void 0 ? void 0 : _b['@signageos/front-applet']));
+            return hasFrontApplet;
+        }
+        catch (_c) {
+            // If we can't load package.json or it's malformed, it's not a valid applet
+            return false;
+        }
+    });
+}
+/**
+ * Validates that the directory is a valid applet directory and throws an error if not.
+ *
+ * @param directoryPath - The directory path to validate
+ * @throws {Error} If the directory is not a valid applet directory
+ */
+function validateAppletDirectory(directoryPath) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const isValid = yield isValidAppletDirectory(directoryPath);
+        if (!isValid) {
+            throw new Error(chalk_1.default.red(`\nThe directory does not appear to be a valid signageOS applet:\n`) +
+                chalk_1.default.white(`  ${directoryPath}\n\n`) +
+                chalk_1.default.yellow(`A valid applet must have ${chalk_1.default.green('@signageos/front-applet')} as a dependency.\n\n`));
+        }
+    });
+}

package/dist/Auth/loginCommand.js

@@ -50,12 +50,14 @@ const chalk_1 = __importDefault(require("chalk"));
 const prompts_1 = __importDefault(require("prompts"));
 const debug_1 = __importDefault(require("debug"));
 const os = __importStar(require("os"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
 const apiVersions_1 = require("@signageos/sdk/dist/RestApi/apiVersions");
 const log_1 = require("@signageos/sdk/dist/Console/log");
 const sosControlHelper_1 = require("@signageos/sdk/dist/SosHelper/sosControlHelper");
 const helper_1 = require("../helper");
 const runControlHelper_1 = require("../RunControl/runControlHelper");
 const parameters_1 = require("../parameters");
+const globalArgs_1 = require("../Command/globalArgs");
 const commandDefinition_1 = require("../Command/commandDefinition");
 const Debug = (0, debug_1.default)('@signageos/cli:Auth:login');
 const OPTION_LIST = [{ name: 'username', type: String, description: `Username or e-mail used for authentication` }];
@@ -100,11 +102,35 @@ exports.login = (0, commandDefinition_1.createCommandDefinition)({
     run(options) {
         return __awaiter(this, void 0, void 0, function* () {
             let identification = options.username;
+            const profile = (0, globalArgs_1.getGlobalProfile)();
+            const configFilePath = (0, sosControlHelper_1.getConfigFilePath)();
+            // Detect a new (non-existent) named profile and prompt for the API URL
+            let promptedApiUrl;
+            if (profile) {
+                let profileExists = false;
+                if (yield fs_extra_1.default.pathExists(configFilePath)) {
+                    const content = (yield fs_extra_1.default.readFile(configFilePath)).toString();
+                    profileExists = content.includes(`[profile ${profile}]`);
+                }
+                if (!profileExists) {
+                    (0, log_1.log)('info', `Profile "${profile}" does not exist in ${configFilePath}. Please enter the server API URL to create it.`);
+                    const { inputApiUrl } = yield (0, prompts_1.default)({
+                        type: 'text',
+                        name: 'inputApiUrl',
+                        message: 'Server API URL',
+                        initial: 'https://api.signageos.io',
+                        validate: (v) => (v.startsWith('http') ? true : 'Must be a valid URL starting with http'),
+                    });
+                    if (!inputApiUrl) {
+                        throw new Error('API URL is required to log in.');
+                    }
+                    promptedApiUrl = inputApiUrl.replace(/\/+$/, '');
+                }
+            }
             const config = yield (0, runControlHelper_1.loadConfig)();
-            const apiUrl = (0, helper_1.getApiUrl)(config);
+            const apiUrl = promptedApiUrl !== null && promptedApiUrl !== void 0 ? promptedApiUrl : (0, helper_1.getApiUrl)(config);
             // Extract domain from API URL to show in prompts
-            const apiUrlObj = new URL(apiUrl);
-            const hostToDisplay = apiUrlObj.hostname;
+            const hostToDisplay = new URL(apiUrl).hostname;
             if (!identification) {
                 const response = yield (0, prompts_1.default)({
                     type: 'text',
@@ -126,7 +152,7 @@ exports.login = (0, commandDefinition_1.createCommandDefinition)({
                 password,
                 apiUrl }, authQueryParams));
             yield (0, runControlHelper_1.saveConfig)({
-                apiUrl: apiUrl !== parameters_1.parameters.apiUrl ? apiUrl : undefined,
+                apiUrl: profile || apiUrl !== parameters_1.parameters.apiUrl ? apiUrl : undefined,
                 identification: tokenId,
                 apiSecurityToken,
             });

package/dist/Command/commandProcessor.js

@@ -20,6 +20,7 @@ const command_line_usage_1 = __importDefault(require("command-line-usage"));
 const command_line_args_1 = __importDefault(require("command-line-args"));
 const packageVersion_1 = require("../Cli/packageVersion");
 const log_1 = require("@signageos/sdk/dist/Console/log");
+const globalArgs_1 = require("./globalArgs");
 const Debug = (0, debug_1.default)('@signageos/cli:Command:processor');
 // Preprocess argv to detect and handle multi-character single-dash options
 function preprocessArgv(argv) {
@@ -40,6 +41,10 @@ function preprocessArgv(argv) {
 }
 function processCommand(currentCommand_1) {
     return __awaiter(this, arguments, void 0, function* (currentCommand, parentOptionList = [], commandIndex = 0) {
+        // Validate mutually exclusive global options once at the root invocation
+        if (commandIndex === 0) {
+            (0, globalArgs_1.validateProfileAndApiUrl)();
+        }
         const nestedOptionList = [...parentOptionList, ...currentCommand.optionList];
         // Preprocess argv to handle multi-character single-dash options that should be treated as unknown
         // rather than being split into individual characters

package/dist/Command/globalArgs.d.ts

@@ -31,3 +31,24 @@ export declare function getGlobalApiUrl(): string | undefined;
  * ```
  */
 export declare function getGlobalProfile(): string;
+/**
+ * Validate that --profile and --api-url are not used together.
+ * These options are mutually exclusive: --profile selects a fully pre-configured
+ * connection from ~/.sosrc (which already includes an api-url), while --api-url
+ * overrides the endpoint directly (implying the default profile).
+ *
+ * @throws {Error} When both --profile and --api-url are present on the command line
+ *
+ * @example
+ * ```bash
+ * # Valid: only --profile
+ * sos --profile staging login
+ *
+ * # Valid: only --api-url
+ * sos --api-url https://custom-api.com login
+ *
+ * # Invalid: both together
+ * sos --profile staging --api-url https://custom-api.com login
+ * ```
+ */
+export declare function validateProfileAndApiUrl(): void;

package/dist/Command/globalArgs.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getGlobalApiUrl = getGlobalApiUrl;
 exports.getGlobalProfile = getGlobalProfile;
+exports.validateProfileAndApiUrl = validateProfileAndApiUrl;
 const command_line_args_1 = __importDefault(require("command-line-args"));
 const generalCommand_1 = require("../generalCommand");
 /**
@@ -46,3 +47,32 @@ function getGlobalProfile() {
     const options = (0, command_line_args_1.default)([generalCommand_1.PROFILE_OPTION], { partial: true });
     return options[generalCommand_1.PROFILE_OPTION.name];
 }
+/**
+ * Validate that --profile and --api-url are not used together.
+ * These options are mutually exclusive: --profile selects a fully pre-configured
+ * connection from ~/.sosrc (which already includes an api-url), while --api-url
+ * overrides the endpoint directly (implying the default profile).
+ *
+ * @throws {Error} When both --profile and --api-url are present on the command line
+ *
+ * @example
+ * ```bash
+ * # Valid: only --profile
+ * sos --profile staging login
+ *
+ * # Valid: only --api-url
+ * sos --api-url https://custom-api.com login
+ *
+ * # Invalid: both together
+ * sos --profile staging --api-url https://custom-api.com login
+ * ```
+ */
+function validateProfileAndApiUrl() {
+    const profile = getGlobalProfile();
+    const apiUrl = getGlobalApiUrl();
+    if (profile !== undefined && apiUrl !== undefined) {
+        throw new Error(`Options --profile and --api-url are mutually exclusive. ` +
+            `--profile selects a pre-configured connection from ~/.sosrc (which already includes an API URL), ` +
+            `while --api-url overrides the API endpoint directly. Use one or the other, not both.`);
+    }
+}