@microtronics/studio-cli 0.54.0 → 0.56.0

package/dist/studio-cli.d.ts

@@ -1897,35 +1897,39 @@ export declare namespace Dependencies {
      * @param cwd
      * @param fs
      * @param libraryName
+     * @param logger
      */
-    export function removeExisting(cwd: URI, fs: LocalFS, libraryName: string): Promise<void>;
+    export function removeExisting(cwd: URI, fs: LocalFS, logger: Log.Logger, libraryName: string): Promise<void>;
     /**
      * Extract the given library.tar.gz array buffer
      * @param cwd
      * @param fs
+     * @param logger
      * @param libraryName
      * @param archiveBuffer
      */
-    export function extractLibraryContent(cwd: URI, fs: LocalFS, libraryName: string, archiveBuffer: ArrayBuffer): Promise<void>;
+    export function extractLibraryContent(cwd: URI, fs: LocalFS, logger: Log.Logger, libraryName: string, archiveBuffer: ArrayBuffer): Promise<void>;
     /**
      * Install the given library with the version that the semver range accepts
      * @param cwd
      * @param fs
+     * @param logger
      * @param env
      * @param token
      * @param publisherIdName
      * @param version
      * @param development - install as development dependency
      */
-    export function installDependency(cwd: URI, fs: LocalFS, env: Globals.ENV, token: string | null, publisherIdName: string, version: string | null, development?: boolean): Promise<undefined>;
+    export function installDependency(cwd: URI, fs: LocalFS, logger: Log.Logger, env: Globals.ENV, token: string | null, publisherIdName: string, version: string | null, development?: boolean): Promise<undefined>;
     /**
      * Install all dependencies that are referenced within the studio manifest
      * @param cwd
      * @param fs
+     * @param logger
      * @param env
      * @param token
      */
-    export function installDependencies(cwd: URI, fs: LocalFS, env: Globals.ENV, token: string | null): Promise<void>;
+    export function installDependencies(cwd: URI, fs: LocalFS, logger: Log.Logger, env: Globals.ENV, token: string | null): Promise<void>;
     /**
      * Uninstall the given library
      * Validates if the library is any sub-dependency of any other library
@@ -1934,7 +1938,15 @@ export declare namespace Dependencies {
      * @param publisherId
      * @param libraryName
      */
-    export function uninstallDependency(cwd: URI, fs: LocalFS, publisherId: string, libraryName: string): Promise<void>;
+    export function uninstallDependency(cwd: URI, fs: LocalFS, logger: Log.Logger, publisherId: string, libraryName: string): Promise<void>;
+    /**
+     * Install npm dependencies in pov and blo working paths if they exist and contain a package.json.
+     * This ensures that a single `studio install` command sets up the entire project.
+     * @param cwd
+     * @param fs
+     * @param logger
+     */
+    export function installNpmInApmParts(cwd: URI, fs: LocalFS, logger: Log.Logger): Promise<void>;
     export interface APMPartLibrary {
         name: string;
         path: URI;
@@ -1946,6 +1958,25 @@ export declare namespace Dependencies {
      * @param apmPart currently only dlo and dfiles are supported
      */
     export function getApmPartDependencies(cwd: URI, fs: LocalFS, apmPart: APM.Part.dlo | APM.Part.dfiles): Promise<APMPartLibrary[]>;
+    /**
+     * Link a library's blo/pov exports into the consuming project's part package.json files.
+     * After a library is extracted, check if it exports blo or pov parts and add `file:` references.
+     * @param cwd
+     * @param fs
+     * @param logger
+     * @param libraryName - short name, e.g. "pets-demo-lib"
+     * @param development
+     */
+    export function linkLibraryApmParts(cwd: URI, fs: LocalFS, logger: Log.Logger, libraryName: string, development?: boolean): Promise<void>;
+    /**
+     * Unlink a library's blo/pov exports from the consuming project's part package.json files.
+     * Removes `file:` references that were added by linkLibraryApmParts.
+     * @param cwd
+     * @param fs
+     * @param logger
+     * @param libraryName - short name, e.g. "pets-demo-lib"
+     */
+    export function unlinkLibraryApmParts(cwd: URI, fs: LocalFS, logger: Log.Logger, libraryName: string): Promise<void>;
 }
 
 /**
@@ -2372,15 +2403,18 @@ export declare enum HttpMethod {
 
 /**
  * Installs the specified dependencies or all dependencies if none are provided.
+ * Additionally runs `npm install` in pov and blo working paths if they exist and contain a package.json,
+ * ensuring a single install command sets up the entire project.
  *
  * @param {URI} cwd - The current working directory where the installation process takes place.
  * @param {LocalFS} fs - The file system interface used for managing files during the installation process.
+ * @param {Log.Logger} logger - Logger instance for logging details during the install process.
  * @param {Globals.ENV} env - The global environment configuration used during the installation.
  * @param {string|null} apiToken - The API token for authentication, if required, or null if not applicable.
  * @param {string[]} dependencies - An array of dependency strings in the format "libraryId@version". If empty, all dependencies will be installed.
  * @return {Promise<void>} A promise that resolves when the installation process completes successfully or logs an error if it fails.
  */
-export declare function install(cwd: URI, fs: LocalFS, env: Globals.ENV, apiToken: string | null, dependencies: string[]): Promise<void>;
+export declare function install(cwd: URI, fs: LocalFS, logger: Log.Logger, env: Globals.ENV, apiToken: string | null, dependencies: string[]): Promise<void>;
 
 export declare namespace Library {
     /**

package/out/api.js

@@ -41,24 +41,29 @@ const log_1 = require("./log");
 Object.defineProperty(exports, "Log", { enumerable: true, get: function () { return log_1.Log; } });
 /**
  * Installs the specified dependencies or all dependencies if none are provided.
+ * Additionally runs `npm install` in pov and blo working paths if they exist and contain a package.json,
+ * ensuring a single install command sets up the entire project.
  *
  * @param {URI} cwd - The current working directory where the installation process takes place.
  * @param {LocalFS} fs - The file system interface used for managing files during the installation process.
+ * @param {Log.Logger} logger - Logger instance for logging details during the install process.
  * @param {Globals.ENV} env - The global environment configuration used during the installation.
  * @param {string|null} apiToken - The API token for authentication, if required, or null if not applicable.
  * @param {string[]} dependencies - An array of dependency strings in the format "libraryId@version". If empty, all dependencies will be installed.
  * @return {Promise<void>} A promise that resolves when the installation process completes successfully or logs an error if it fails.
  */
-async function install(cwd, fs, env, apiToken, dependencies) {
+async function install(cwd, fs, logger, env, apiToken, dependencies) {
     if (dependencies.length > 0) {
         for (const dependency of dependencies) {
             const [libraryId, version] = dependency.split('@');
-            await dependencies_1.Dependencies.installDependency(cwd, fs, env, apiToken, libraryId, version || null);
+            await dependencies_1.Dependencies.installDependency(cwd, fs, logger, env, apiToken, libraryId, version || null);
         }
     }
     else {
-        return await dependencies_1.Dependencies.installDependencies(cwd, fs, env, apiToken);
+        await dependencies_1.Dependencies.installDependencies(cwd, fs, logger, env, apiToken);
     }
+    // Run npm install in pov/blo working paths if they have a package.json
+    await dependencies_1.Dependencies.installNpmInApmParts(cwd, fs, logger);
 }
 /**
  * Builds the specified parts of the project located in the given directory.

package/out/dde/dde.js

@@ -396,7 +396,7 @@ var DDE;
         const manifest = await manifest_1.Manifest.read(cwd, fs);
         const dependencies = await getDependencies(cwd, fs, manifest);
         const resolvedConfig = await globals_1.Globals.read(cwd, fs, logger);
-        const autoInc = (0, dlo_1.generateAutoIncFromMap)(ddeJSON, resolvedConfig.flat, manifest);
+        const autoInc = (0, dlo_1.generateAutoIncFromMap)(ddeJSON, resolvedConfig, manifest);
         const appAutoDDE = new dlo_1.AutoDDEGenerator(manifest, ddeJSON, null);
         const appDDEInc = appAutoDDE.generate();
         // generate AutoDDe Files for the libraries:

package/out/dde/fileGenerators/dlo.js

@@ -97,7 +97,7 @@ function dloCoreSupportsFlags(manifest) {
     return semver.gte(releaseVersion, '1.1.0');
 }
 // eslint-disable-next-line sonarjs/cognitive-complexity
-function generateAutoIncFromMap(ddeMap, globalDefines, manifest) {
+function generateAutoIncFromMap(ddeMap, resolvedConfig, manifest) {
     const _pwn = []; // sample code output for pawn
     const pwn = _pwn.push.bind(_pwn);
     function pwn_section(s) {
@@ -139,8 +139,24 @@ function generateAutoIncFromMap(ddeMap, globalDefines, manifest) {
     /**
      * generate global dlo defines if there are any
      */
+    const globalDefines = resolvedConfig.flat;
+    const { definesWithSource } = resolvedConfig;
     pwn_section('GLOBAL DEFINES');
     for (const [define, value] of Object.entries(globalDefines)) {
+        const comment = definesWithSource[define]?.comment;
+        if (comment) {
+            const lines = comment.split('\n');
+            if (lines.length === 1) {
+                pwn(`/** ${lines[0]} */`);
+            }
+            else {
+                pwn('/**');
+                for (const line of lines) {
+                    pwn(` * ${line}`);
+                }
+                pwn(' */');
+            }
+        }
         const valueIsDefine = Object.hasOwn(globalDefines, value);
         addDefinition(define, `${value}`, valueIsDefine);
     }

package/out/dependencies.js

@@ -30,9 +30,11 @@ const semver = __importStar(require("semver"));
 const registryAPI_1 = require("./registryAPI");
 const defaultFiles_1 = require("./defaultFiles");
 const apm_1 = require("./package/apm");
+const child_process = __importStar(require("node:child_process"));
 const tinytar = require('tinytar-fix');
 const pako = require('pako');
 exports.LIB_DEPS_PATH = '.studio/libdeps';
+const PACKAGE_JSON = 'package.json';
 var Dependencies;
 (function (Dependencies) {
     /**
@@ -163,11 +165,12 @@ var Dependencies;
      * @param cwd
      * @param fs
      * @param libraryName
+     * @param logger
      */
-    async function removeExisting(cwd, fs, libraryName) {
+    async function removeExisting(cwd, fs, logger, libraryName) {
         const libraryPath = vscode_uri_1.Utils.joinPath(cwd, exports.LIB_DEPS_PATH, libraryName);
         await fs.rm(libraryPath).catch(err => {
-            console.error('removeExisting', err);
+            logger.error('removeExisting', err);
         });
     }
     Dependencies.removeExisting = removeExisting;
@@ -175,19 +178,20 @@ var Dependencies;
      * Extract the given library.tar.gz array buffer
      * @param cwd
      * @param fs
+     * @param logger
      * @param libraryName
      * @param archiveBuffer
      */
-    async function extractLibraryContent(cwd, fs, libraryName, archiveBuffer) {
+    async function extractLibraryContent(cwd, fs, logger, libraryName, archiveBuffer) {
         const files = tinytar.untar(pako.ungzip(archiveBuffer));
-        await removeExisting(cwd, fs, libraryName);
+        await removeExisting(cwd, fs, logger, libraryName);
         for (const file of files.values()) {
             try {
                 const filePath = vscode_uri_1.Utils.joinPath(cwd, exports.LIB_DEPS_PATH, libraryName, file.name);
                 await fs.writeFile(filePath, file.data);
             }
             catch (e) {
-                console.error('Extracting lib', e);
+                logger.error('Extracting lib', e);
             }
         }
     }
@@ -196,19 +200,20 @@ var Dependencies;
      * Install the given library with the version that the semver range accepts
      * @param cwd
      * @param fs
+     * @param logger
      * @param env
      * @param token
      * @param publisherIdName
      * @param version
      * @param development - install as development dependency
      */
-    async function installDependency(cwd, fs, env, token, publisherIdName, version, development = false) {
+    async function installDependency(cwd, fs, logger, env, token, publisherIdName, version, development = false) {
         const [publisherId, libraryName] = publisherIdName.split('/');
         if (version && (await isDependencyInstalled(cwd, fs, publisherId, libraryName, version))) {
             return;
         }
         // just remove any existing version of this library.
-        await removeExisting(cwd, fs, libraryName);
+        await removeExisting(cwd, fs, logger, libraryName);
         const libraryProfile = await registryAPI_1.Registry.getLibraryProfile(token, publisherId, libraryName, env);
         const versionToDownload = version
             ? libraryProfile.versions?.find(versionInfo => {
@@ -229,7 +234,7 @@ var Dependencies;
         await validateDependencyTree(cwd, fs, newDependencies, development);
         // install sub dependencies first
         for (const [libraryName, libraryVersion] of Object.entries(librarySubDependencies)) {
-            await installDependency(cwd, fs, env, token, libraryName, libraryVersion, development);
+            await installDependency(cwd, fs, logger, env, token, libraryName, libraryVersion, development);
         }
         const libraryArchive = versionToDownload.files.find(file => {
             return file.name === 'library.tar.gz';
@@ -238,7 +243,8 @@ var Dependencies;
             throw new Error(`Library ${publisherIdName} has no content!`);
         }
         const libraryBuffer = await registryAPI_1.Registry.fetchCustomContent(token, libraryArchive.downloadUrl);
-        await extractLibraryContent(cwd, fs, libraryName, libraryBuffer);
+        await extractLibraryContent(cwd, fs, logger, libraryName, libraryBuffer);
+        await linkLibraryApmParts(cwd, fs, logger, libraryName, development);
         // update manifest
         const manifest = await manifest_1.Manifest.read(cwd, fs);
         const dependencies = manifest.libraryDependencies || {};
@@ -255,10 +261,11 @@ var Dependencies;
      * Install all dependencies that are referenced within the studio manifest
      * @param cwd
      * @param fs
+     * @param logger
      * @param env
      * @param token
      */
-    async function installDependencies(cwd, fs, env, token) {
+    async function installDependencies(cwd, fs, logger, env, token) {
         const manifest = await manifest_1.Manifest.read(cwd, fs);
         const dependencies = manifest.libraryDependencies || {};
         const devDependencies = manifest.libraryDevDependencies || {};
@@ -266,9 +273,16 @@ var Dependencies;
         for (const [libraryName, libraryVersion] of Object.entries(allDependencies)) {
             const isDevelopment = Object.hasOwn(devDependencies, libraryName);
             // update the tree version with the actual installed version
-            await installDependency(cwd, fs, env, token, libraryName, libraryVersion, isDevelopment);
+            await installDependency(cwd, fs, logger, env, token, libraryName, libraryVersion, isDevelopment);
         }
-        console.log(`Installed ${Object.entries(allDependencies).length} dependencies`);
+        // Ensure blo/pov file: references are linked for all dependencies
+        // (installDependency skips linking when the dependency is already installed)
+        for (const [libraryId] of Object.entries(allDependencies)) {
+            const libName = dependencyIdToName(libraryId);
+            const isDevelopment = Object.hasOwn(devDependencies, libraryId);
+            await linkLibraryApmParts(cwd, fs, logger, libName, isDevelopment);
+        }
+        logger.done(`Installed ${Object.entries(allDependencies).length} dependencies`);
     }
     Dependencies.installDependencies = installDependencies;
     /**
@@ -279,7 +293,7 @@ var Dependencies;
      * @param publisherId
      * @param libraryName
      */
-    async function uninstallDependency(cwd, fs, publisherId, libraryName) {
+    async function uninstallDependency(cwd, fs, logger, publisherId, libraryName) {
         const manifest = await manifest_1.Manifest.read(cwd, fs);
         const dependencies = manifest.libraryDependencies || {};
         const devDependencies = manifest.libraryDevDependencies || {};
@@ -288,7 +302,8 @@ var Dependencies;
         delete allDependencies[libraryId];
         const validatedDependencies = await validateIfLibraryCanBeRemoved(cwd, fs, allDependencies);
         if (!Object.hasOwn(validatedDependencies, libraryId)) {
-            await removeExisting(cwd, fs, libraryName);
+            await unlinkLibraryApmParts(cwd, fs, logger, libraryName);
+            await removeExisting(cwd, fs, logger, libraryName);
             delete devDependencies[libraryId];
             delete dependencies[libraryId];
             await manifest_1.Manifest.write(cwd, fs, manifest);
@@ -298,6 +313,33 @@ var Dependencies;
         }
     }
     Dependencies.uninstallDependency = uninstallDependency;
+    /**
+     * Install npm dependencies in pov and blo working paths if they exist and contain a package.json.
+     * This ensures that a single `studio install` command sets up the entire project.
+     * @param cwd
+     * @param fs
+     * @param logger
+     */
+    async function installNpmInApmParts(cwd, fs, logger) {
+        const manifest = await manifest_1.Manifest.read(cwd, fs);
+        const parts = [];
+        if (manifest.pov?.details?.workingPath) {
+            parts.push({ name: 'pov', workingPath: manifest.pov.details.workingPath });
+        }
+        if (manifest.blo?.workingPath) {
+            parts.push({ name: 'blo', workingPath: manifest.blo.workingPath });
+        }
+        for (const { name, workingPath } of parts) {
+            const partDir = vscode_uri_1.Utils.joinPath(cwd, workingPath);
+            const packageJsonPath = vscode_uri_1.Utils.joinPath(partDir, PACKAGE_JSON);
+            const hasPackageJson = await fs.stat(packageJsonPath);
+            if (hasPackageJson) {
+                logger.info(`Installing npm dependencies for ${name} (${workingPath})...`);
+                await execNpmInstall(partDir, logger);
+            }
+        }
+    }
+    Dependencies.installNpmInApmParts = installNpmInApmParts;
     /**
      * Get all libraries that have dlo source
      * @param cwd
@@ -336,7 +378,100 @@ var Dependencies;
         return apmDependencies;
     }
     Dependencies.getApmPartDependencies = getApmPartDependencies;
+    /**
+     * Link a library's blo/pov exports into the consuming project's part package.json files.
+     * After a library is extracted, check if it exports blo or pov parts and add `file:` references.
+     * @param cwd
+     * @param fs
+     * @param logger
+     * @param libraryName - short name, e.g. "pets-demo-lib"
+     * @param development
+     */
+    async function linkLibraryApmParts(cwd, fs, logger, libraryName, development) {
+        const manifest = await manifest_1.Manifest.read(cwd, fs);
+        const partConfigs = [
+            { partName: 'blo', partDistPath: 'blo', workingPath: manifest.blo?.workingPath },
+            { partName: 'pov', partDistPath: 'pov/details', workingPath: manifest.pov?.details?.workingPath }
+        ];
+        for (const { partName, partDistPath, workingPath } of partConfigs) {
+            if (!workingPath) {
+                continue;
+            }
+            const libPartPackageJson = vscode_uri_1.Utils.joinPath(cwd, exports.LIB_DEPS_PATH, libraryName, 'dist', ...partDistPath.split('/'), PACKAGE_JSON);
+            const libPartExists = await fs.stat(libPartPackageJson);
+            if (!libPartExists) {
+                continue;
+            }
+            try {
+                const pkg = await readPartPackageJson(cwd, fs, workingPath);
+                const depsKey = development ? 'devDependencies' : 'dependencies';
+                pkg[depsKey] = pkg[depsKey] || {};
+                const depth = workingPath.split('/').length;
+                const relativePrefix = Array(depth).fill('..').join('/');
+                pkg[depsKey][libraryName] = `file:${relativePrefix}/${exports.LIB_DEPS_PATH}/${libraryName}/dist/${partDistPath}`;
+                await writePartPackageJson(cwd, fs, workingPath, pkg);
+                logger.info(`Linked ${libraryName} to ${partName} (${workingPath})`);
+            }
+            catch (e) {
+                logger.warn(`Could not link ${libraryName} to ${partName}: ${e}`);
+            }
+        }
+    }
+    Dependencies.linkLibraryApmParts = linkLibraryApmParts;
+    /**
+     * Unlink a library's blo/pov exports from the consuming project's part package.json files.
+     * Removes `file:` references that were added by linkLibraryApmParts.
+     * @param cwd
+     * @param fs
+     * @param logger
+     * @param libraryName - short name, e.g. "pets-demo-lib"
+     */
+    async function unlinkLibraryApmParts(cwd, fs, logger, libraryName) {
+        const manifest = await manifest_1.Manifest.read(cwd, fs);
+        const partConfigs = [
+            { partName: 'blo', workingPath: manifest.blo?.workingPath },
+            { partName: 'pov', workingPath: manifest.pov?.details?.workingPath }
+        ];
+        for (const { partName, workingPath } of partConfigs) {
+            if (!workingPath) {
+                continue;
+            }
+            try {
+                const pkg = await readPartPackageJson(cwd, fs, workingPath);
+                let changed = false;
+                // Remove from dependencies if it's a file: reference
+                if (pkg.dependencies?.[libraryName]?.startsWith('file:')) {
+                    delete pkg.dependencies[libraryName];
+                    changed = true;
+                }
+                // Remove from devDependencies if it's a file: reference
+                if (pkg.devDependencies?.[libraryName]?.startsWith('file:')) {
+                    delete pkg.devDependencies[libraryName];
+                    changed = true;
+                }
+                if (changed) {
+                    await writePartPackageJson(cwd, fs, workingPath, pkg);
+                    logger.info(`Unlinked ${libraryName} from ${partName}`);
+                }
+            }
+            catch (e) {
+                logger.warn(`Could not unlink ${libraryName} from ${partName}: ${e}`);
+            }
+        }
+    }
+    Dependencies.unlinkLibraryApmParts = unlinkLibraryApmParts;
 })(Dependencies || (exports.Dependencies = Dependencies = {}));
+async function readPartPackageJson(cwd, fs, workingPath) {
+    const packageJsonPath = vscode_uri_1.Utils.joinPath(cwd, workingPath, PACKAGE_JSON);
+    const data = await fs.readFile(packageJsonPath);
+    const text = new TextDecoder().decode(data);
+    return JSON.parse(text);
+}
+async function writePartPackageJson(cwd, fs, workingPath, pkg) {
+    const packageJsonPath = vscode_uri_1.Utils.joinPath(cwd, workingPath, PACKAGE_JSON);
+    const content = JSON.stringify(pkg, null, '\t') + '\n';
+    await fs.writeFile(packageJsonPath, content);
+}
 async function fetchStudioJson(token, studioJsonURL) {
     return await registryAPI_1.Registry.fetchCustomContent(token, studioJsonURL, true);
 }
@@ -419,4 +554,25 @@ function buildDependencyEntry(publisherId, libraryId, libraryVersion) {
         libraryId: `${publisherId}/${libraryId}`
     };
 }
+/**
+ * Execute `npm install` in the given directory
+ * @param cwd - working directory where npm install should be executed
+ * @param logger
+ */
+function execNpmInstall(cwd, logger) {
+    return new Promise((resolve, reject) => {
+        child_process.exec('npm ci', { cwd: cwd.fsPath, env: process.env }, (error, stdout, stderr) => {
+            if (stdout) {
+                logger.log(stdout);
+            }
+            if (stderr) {
+                logger.error(stderr);
+            }
+            if (error) {
+                reject(error);
+            }
+            resolve();
+        });
+    });
+}
 //# sourceMappingURL=dependencies.js.map

package/out/globals.js

@@ -67,10 +67,10 @@ var Globals;
             const depPath = dependencies_1.Dependencies.dependencyToPath(cwd, dependencyId);
             const name = dependencies_1.Dependencies.dependencyIdToName(dependencyId);
             const libIniPath = vscode_uri_1.Utils.joinPath(depPath, DLO_PATH, `${name}.ini`);
-            await mergeIniFile(fs, libIniPath, allDefines, sections, definesWithSource);
+            await mergeIniFile(fs, libIniPath, allDefines, sections, definesWithSource, name);
             // defaults.ini files
             const libDefaultsPath = vscode_uri_1.Utils.joinPath(depPath, defaultFiles_1.DefaultFiles.filePaths.defaultsIni);
-            await mergeIniFile(fs, libDefaultsPath, allDefines, sections, definesWithSource);
+            await mergeIniFile(fs, libDefaultsPath, allDefines, sections, definesWithSource, name);
         }
         // Load the library project's specific ini file (deprecated location)
         if (manifest_1.Manifest.isLibrary(manifest)) {
@@ -78,7 +78,7 @@ var Globals;
             if (logger && (await fs.stat(libIni))) {
                 logger.warn(`dlo/${manifest.name}.ini is deprecated. Please migrate your defines to defaults.ini in the project root.`);
             }
-            await mergeIniFile(fs, libIni, allDefines, sections, definesWithSource);
+            await mergeIniFile(fs, libIni, allDefines, sections, definesWithSource, manifest.name);
         }
         // Load the project's main.ini and overwrite existing defines (deprecated location)
         const mainIniRelPath = manifest.dlo?.iniFile || defaultFiles_1.DefaultFiles.filePaths.dlo.mainINI;
@@ -86,17 +86,18 @@ var Globals;
         if (logger && (await fs.stat(mainIni))) {
             logger.warn(`${mainIniRelPath} is deprecated. Please migrate your defines to app.ini in the project root.`);
         }
-        await mergeIniFile(fs, mainIni, allDefines, sections, definesWithSource);
+        const mainIniLabel = iniFileLabel(mainIniRelPath);
+        await mergeIniFile(fs, mainIni, allDefines, sections, definesWithSource, mainIniLabel);
         // Project root: defaults.ini (library) or app.ini (app/addon/analytics)
         if (manifest_1.Manifest.isLibrary(manifest)) {
             const defaultsIni = vscode_uri_1.Utils.joinPath(cwd, defaultFiles_1.DefaultFiles.filePaths.defaultsIni);
-            await mergeIniFile(fs, defaultsIni, allDefines, sections, definesWithSource);
+            await mergeIniFile(fs, defaultsIni, allDefines, sections, definesWithSource, 'defaults');
         }
         // Snapshot defaults-only state before app.ini merge (for library dual-defines)
         const defaultsOnly = snapshotDefaultsOnly(manifest, allDefines, sections, definesWithSource);
         // app.ini is always loaded (provides local dev overrides for libraries, main config for apps)
         const appIni = vscode_uri_1.Utils.joinPath(cwd, defaultFiles_1.DefaultFiles.filePaths.appIni);
-        await mergeIniFile(fs, appIni, allDefines, sections, definesWithSource);
+        await mergeIniFile(fs, appIni, allDefines, sections, definesWithSource, 'app');
         return { flat: allDefines, sections, definesWithSource, defaultsOnly };
     }
     Globals.read = read;
@@ -269,10 +270,35 @@ function formatJsDoc(comment) {
 function isNumericValue(value) {
     return value !== '' && !isNaN(Number(value));
 }
+/**
+ * Derive a human-readable source label from an ini file path.
+ * Strips the directory prefix and `.ini` extension.
+ * E.g. `dlo/main.ini` → `main`, `app.ini` → `app`.
+ */
+function iniFileLabel(relPath) {
+    const filename = relPath.split('/').pop() || relPath;
+    return filename.replace(/\.ini$/i, '');
+}
+/**
+ * Merge an incoming comment with an existing one.
+ *
+ * - Both present  → join existing (already prefixed) and new (prefixed) with `\n`
+ * - Only existing → keep it
+ * - Only new      → use it (prefixed)
+ * - Neither       → undefined
+ */
+function mergeComment(existingComment, newRawComment, sourceLabel) {
+    const prefixedNew = newRawComment ? `${sourceLabel}: ${newRawComment}` : undefined;
+    if (existingComment && prefixedNew) {
+        return `${existingComment}\n${prefixedNew}`;
+    }
+    return prefixedNew || existingComment;
+}
 /**
  * Create a DefineEntry, attaching a comment from the comment map if available.
+ * The comment is prefixed with the source label for provenance tracking.
  */
-function createDefineEntry(stringValue, fileUri, lines, key, sectionName, commentMap) {
+function createDefineEntry(stringValue, fileUri, lines, key, sectionName, commentMap, sourceLabel) {
     const flatKey = sectionName ? `${sectionName}_${key}` : key;
     const entry = {
         value: stringValue,
@@ -280,23 +306,26 @@ function createDefineEntry(stringValue, fileUri, lines, key, sectionName, commen
         sourceLine: findLineNumber(lines, key, sectionName)
     };
     if (commentMap[flatKey]) {
-        entry.comment = commentMap[flatKey];
+        entry.comment = `${sourceLabel}: ${commentMap[flatKey]}`;
     }
     return entry;
 }
 /**
  * Merge all keys from a parsed ini section into the accumulators.
  */
-function mergeSectionEntries(sectionName, sectionData, allDefines, sections, definesWithSource, fileUri, lines, commentMap) {
+function mergeSectionEntries(sectionName, sectionData, allDefines, sections, definesWithSource, fileUri, lines, commentMap, sourceLabel) {
     if (!sections[sectionName]) {
         sections[sectionName] = {};
     }
     for (const [key, sectionValue] of Object.entries(sectionData)) {
         const flatKey = `${sectionName}_${key}`;
+        const rawComment = commentMap[flatKey];
         const stringValue = `${sectionValue}`;
         allDefines[flatKey] = stringValue;
         sections[sectionName][key] = stringValue;
-        definesWithSource[flatKey] = createDefineEntry(stringValue, fileUri, lines, key, sectionName, commentMap);
+        const newEntry = createDefineEntry(stringValue, fileUri, lines, key, sectionName, commentMap, sourceLabel);
+        newEntry.comment = mergeComment(definesWithSource[flatKey]?.comment, rawComment, sourceLabel);
+        definesWithSource[flatKey] = newEntry;
     }
 }
 /**
@@ -309,7 +338,7 @@ function mergeSectionEntries(sectionName, sectionData, allDefines, sections, def
  * @param sections - accumulated sectioned config (mutated)
  * @param definesWithSource - accumulated source tracking (mutated)
  */
-async function mergeIniFile(fs, filePath, allDefines, sections, definesWithSource) {
+async function mergeIniFile(fs, filePath, allDefines, sections, definesWithSource, sourceLabel) {
     // early return if the file doesn't exist
     if (!(await fs.stat(filePath))) {
         return;
@@ -322,12 +351,15 @@ async function mergeIniFile(fs, filePath, allDefines, sections, definesWithSourc
     const commentMap = extractComments(rawText);
     for (const [sectionOrKey, value] of Object.entries(parsed)) {
         if (typeof value === 'object' && value !== null) {
-            mergeSectionEntries(sectionOrKey, value, allDefines, sections, definesWithSource, fileUri, lines, commentMap);
+            mergeSectionEntries(sectionOrKey, value, allDefines, sections, definesWithSource, fileUri, lines, commentMap, sourceLabel);
         }
         else {
+            const rawComment = commentMap[sectionOrKey];
             const stringValue = `${value}`;
             allDefines[sectionOrKey] = stringValue;
-            definesWithSource[sectionOrKey] = createDefineEntry(stringValue, fileUri, lines, sectionOrKey, null, commentMap);
+            const newEntry = createDefineEntry(stringValue, fileUri, lines, sectionOrKey, null, commentMap, sourceLabel);
+            newEntry.comment = mergeComment(definesWithSource[sectionOrKey]?.comment, rawComment, sourceLabel);
+            definesWithSource[sectionOrKey] = newEntry;
         }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@microtronics/studio-cli",
-	"version": "0.54.0",
+	"version": "0.56.0",
 	"description": "Microtronics Studio CLI Tool",
 	"main": "./out/api.js",
 	"typings": "./dist/studio-cli.d.ts",