@tenonhq/sincronia-core 0.0.80 → 0.0.82

package/dist/FileUtils.js

@@ -36,7 +36,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.writeFileForce = exports.writeSNFileForce = exports.writeSNFileIfNotExists = exports.writeBuildFile = exports.summarizeFile = exports.encodedPathsToFilePaths = exports.isValidPath = exports.splitEncodedPaths = exports.getPathsInPath = exports.isDirectory = exports.toAbsolutePath = exports.getFileContextFromPath = exports.getFileContextWithSkipReason = exports.getBuildExt = exports.isUnderPath = exports.appendToPath = exports.pathExists = exports.createDirRecursively = exports.writeSNFileCurry = exports.writeScopeManifest = exports.writeManifestFile = exports.SNFileExists = void 0;
+exports.writeFileForce = exports.writeSNFileForce = exports.writeSNFileIfNotExists = exports.writeBuildFile = exports.summarizeFile = exports.encodedPathsToFilePaths = exports.isValidPath = exports.splitEncodedPaths = exports.getPathsInPath = exports.isDirectory = exports.toAbsolutePath = exports.getFileContextFromPath = exports.getFileContextWithSkipReason = exports.getBuildExt = exports.isUnderPath = exports.appendToPath = exports.pathExists = exports.createDirRecursively = exports.writeSNFileIfDifferent = exports.writeSNFileCurry = exports.writeScopeManifest = exports.writeManifestFile = exports.SNFileExists = void 0;
 exports.writeEnvVar = writeEnvVar;
 exports.writeEnvVars = writeEnvVars;
 const constants_1 = require("./constants");
@@ -103,6 +103,45 @@ const writeSNFileCurry = (checkExists) => async (file, parentPath) => {
     }
 };
 exports.writeSNFileCurry = writeSNFileCurry;
+/**
+ * Writes the SN file to disk only if the local content differs from `file.content`.
+ * Returns `true` if the file was written (missing or differed), `false` if skipped.
+ *
+ * Used by `sinc refresh` to pull ServiceNow-side edits without churning unchanged
+ * files (preserves mtime, avoids noisy watchers, keeps diff output clean).
+ */
+const writeSNFileIfDifferent = async (file, parentPath) => {
+    let { name, type, content = "" } = file;
+    if (!content)
+        content = "";
+    const fullPath = path_1.default.join(parentPath, `${name}.${type}`);
+    let localContent = null;
+    try {
+        localContent = await fs_1.promises.readFile(fullPath, "utf8");
+    }
+    catch (e) {
+        localContent = null;
+    }
+    if (localContent === content) {
+        FileLogger_1.fileLogger.debug("Unchanged: " + fullPath);
+        return false;
+    }
+    if (localContent !== null) {
+        FileLogger_1.fileLogger.debug("Overwriting local content (differs from instance): " + fullPath);
+    }
+    else {
+        FileLogger_1.fileLogger.debug("Writing (missing locally): " + fullPath);
+    }
+    try {
+        await fs_1.promises.writeFile(fullPath, content);
+        return true;
+    }
+    catch (error) {
+        FileLogger_1.fileLogger.error("Failed to write " + fullPath + ":", error);
+        throw error;
+    }
+};
+exports.writeSNFileIfDifferent = writeSNFileIfDifferent;
 const createDirRecursively = async (path) => {
     await fs_1.promises.mkdir(path, { recursive: true });
 };

package/dist/MultiScopeWatcher.js

@@ -220,7 +220,8 @@ class MultiScopeWatcherManager {
                 if (curSysId && curName) {
                     var isDefault = curName === "Default" || curName.toLowerCase().indexOf("default") !== -1;
                     if (isDefault) {
-                        Logger_1.logger.warn(`[${scopeName}] No update set configured and current update set is Default. ` +
+                        Logger_1.logger.warn(`[${scopeName}] No update set configured for scope ${scopeName}. ` +
+                            `Changes will go to Default. ` +
                             `Use sinc createUpdateSet or activate a task in the dashboard.`);
                     }
                     else {
@@ -233,12 +234,14 @@ class MultiScopeWatcherManager {
                 }
                 else {
                     Logger_1.logger.warn(`[${scopeName}] No update set configured for scope ${scopeName}. ` +
+                        `Changes will go to Default. ` +
                         `Use sinc createUpdateSet or activate a task in the dashboard.`);
                 }
             }
             catch (queryErr) {
-                Logger_1.logger.warn(`[${scopeName}] No update set configured and could not query current update set. ` +
-                    `Changes will use direct Table API. Use sinc createUpdateSet or activate a task in the dashboard.`);
+                Logger_1.logger.warn(`[${scopeName}] No update set configured for scope ${scopeName}. ` +
+                    `Changes will go to Default (could not query current update set). ` +
+                    `Use sinc createUpdateSet or activate a task in the dashboard.`);
             }
             return;
         }

package/dist/appUtils.js

@@ -36,7 +36,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createAndAssignUpdateSet = exports.swapScope = exports.buildFiles = exports.summarizeRecord = exports.pushFiles = exports.getAppFileList = exports.groupAppFiles = exports.processMissingFiles = exports.findMissingFiles = exports.syncManifest = exports.processManifest = exports.normalizeManifestKeys = void 0;
+exports.createAndAssignUpdateSet = exports.swapScope = exports.buildFiles = exports.summarizeRecord = exports.pushFiles = exports.getAppFileList = exports.groupAppFiles = exports.processMissingFiles = exports.refreshAllFiles = exports.findMissingFiles = exports.syncManifest = exports.processManifest = exports.normalizeManifestKeys = void 0;
 const path_1 = __importDefault(require("path"));
 const fs_1 = __importDefault(require("fs"));
 const progress_1 = __importDefault(require("progress"));
@@ -46,6 +46,7 @@ const constants_1 = require("./constants");
 const PluginManager_1 = __importDefault(require("./PluginManager"));
 const FileLogger_1 = require("./FileLogger");
 const snClient_1 = require("./snClient");
+const benchmark_1 = require("./benchmark");
 const Logger_1 = require("./Logger");
 const genericUtils_1 = require("./genericUtils");
 const getUpdateSetConfig = () => {
@@ -106,9 +107,37 @@ const countRecordsInTables = (tables) => {
         return sum + Object.keys(tables[tableName].records).length;
     }, 0);
 };
-const processTablesInManifest = async (tables, forceWrite, sourcePath, onRecordProcessed) => {
+const processTablesInManifest = async (tables, forceWrite, sourcePath, onRecordProcessed, scope) => {
     var basePath = sourcePath || ConfigManager.getSourcePath();
-    const tableNames = Object.keys(tables);
+    var tableNames = Object.keys(tables);
+    // Defense-in-depth: filter out any table not in the resolved whitelist before
+    // writing to disk. Protects against upstream defects that let non-whitelisted
+    // tables through (e.g. server-side manifest fanout, stale manifest entries).
+    if (scope) {
+        try {
+            var resolved = ConfigManager.resolveConfigForScope(scope);
+            var allowed = resolved.tables;
+            if (allowed && allowed.length > 0) {
+                var skipped = [];
+                tableNames = tableNames.filter(function (t) {
+                    if (allowed.indexOf(t) === -1) {
+                        skipped.push(t);
+                        return false;
+                    }
+                    return true;
+                });
+                if (skipped.length > 0) {
+                    FileLogger_1.fileLogger.debug("processTablesInManifest: dropped " + skipped.length +
+                        " non-whitelisted tables for scope '" + scope + "': " + skipped.join(", "));
+                }
+            }
+        }
+        catch (e) {
+            // Config resolution can fail for legacy single-scope manifests; fall
+            // through and process whatever the manifest contains.
+            FileLogger_1.fileLogger.debug("processTablesInManifest: could not resolve whitelist for scope '" + scope + "'");
+        }
+    }
     await (0, genericUtils_1.processBatched)(tableNames, constants_1.CONCURRENCY_TABLES, function (tableName) {
         return processRecsInManTable(path_1.default.join(basePath, tableName), tables[tableName], forceWrite, onRecordProcessed);
     });
@@ -149,7 +178,7 @@ const processManifest = async (manifest, forceWrite = false, sourcePath) => {
         scope: manifest.scope || "default",
         total: recordCount,
     });
-    await processTablesInManifest(manifest.tables, forceWrite, sourcePath, progress.tick);
+    await processTablesInManifest(manifest.tables, forceWrite, sourcePath, progress.tick, manifest.scope);
     if (manifest.scope) {
         await fUtils.writeScopeManifest(manifest.scope, manifest);
     }
@@ -158,23 +187,74 @@ const processManifest = async (manifest, forceWrite = false, sourcePath) => {
     }
 };
 exports.processManifest = processManifest;
-const syncManifest = async (scope) => {
+const syncManifest = async (scope, options = {}) => {
+    // Top-level entry owns the collector lifecycle. Recursive calls (all-scopes
+    // → per-scope) inherit the collector via options._benchmarkCollector.
+    var isBenchmarkOwner = false;
+    var collector = options._benchmarkCollector;
+    if (options.benchmark && !collector) {
+        collector = new benchmark_1.BenchmarkCollector();
+        (0, snClient_1.setBenchmarkSink)(collector);
+        isBenchmarkOwner = true;
+    }
     try {
         const curManifest = await ConfigManager.getManifest();
         if (!curManifest)
             throw new Error("No manifest file loaded!");
+        const config = ConfigManager.getConfig();
+        const declaredScopes = (config.scopes && Object.keys(config.scopes)) || [];
         // If a specific scope is provided, sync only that scope
         if (scope) {
+            // Scope whitelist gate: refuse to refresh scopes not declared in sinc.config.js.
+            // Without this, stale entries in sinc.manifest.json leak undeclared scopes into
+            // the refresh loop (see RFC-0004 / sys_alias debris incident 2026-04-14).
+            if (declaredScopes.length > 0 && declaredScopes.indexOf(scope) === -1) {
+                Logger_1.logger.warn("Skipping scope '" + scope + "' — not declared in sinc.config.js `scopes`. " +
+                    "Add it to config.scopes to sync, or remove its manifest file.");
+                FileLogger_1.fileLogger.debug("syncManifest: skipped undeclared scope '" + scope + "'");
+                return;
+            }
             Logger_1.logger.info("Refreshing scope: " + scope + "...");
             const client = (0, snClient_1.defaultClient)();
-            const config = ConfigManager.getConfig();
-            // Resolve scope-specific source directory
+            // Resolve scope-specific source directory + table whitelist
             var scopeSourcePath = ConfigManager.getSourcePathForScope(scope);
+            var resolvedConfig = ConfigManager.resolveConfigForScope(scope);
+            var allowedTables = resolvedConfig.tables;
             const newManifest = (0, exports.normalizeManifestKeys)(await (0, snClient_1.unwrapSNResponse)(client.getManifest(scope, config)));
+            // Table whitelist gate: drop any table the server returned that is not in
+            // the resolved _tables whitelist for this scope. Mirrors the filter in
+            // commands.ts downloadCommand() and allScopesCommands.ts processScope().
+            if (allowedTables && allowedTables.length > 0) {
+                var manifestTableNames = Object.keys(newManifest.tables || {});
+                var filteredTables = {};
+                var skippedCount = 0;
+                for (var t = 0; t < manifestTableNames.length; t++) {
+                    var tName = manifestTableNames[t];
+                    if (allowedTables.indexOf(tName) !== -1) {
+                        filteredTables[tName] = newManifest.tables[tName];
+                    }
+                    else {
+                        skippedCount++;
+                    }
+                }
+                if (skippedCount > 0) {
+                    FileLogger_1.fileLogger.debug("syncManifest: filtered " + skippedCount + " tables not in _tables whitelist for " +
+                        scope + " (kept " + Object.keys(filteredTables).length + " of " + manifestTableNames.length + ")");
+                }
+                newManifest.tables = filteredTables;
+            }
+            else {
+                Logger_1.logger.warn("No _tables whitelist defined — writing ALL tables for " + scope);
+            }
             const refreshTableCount = Object.keys(newManifest.tables).length;
             FileLogger_1.fileLogger.debug("Refreshed manifest for " + scope + ": " + refreshTableCount + " tables");
             await fUtils.writeScopeManifest(scope, newManifest);
-            await (0, exports.processMissingFiles)(newManifest, scopeSourcePath);
+            if (collector)
+                collector.startScope(scope);
+            await (0, exports.refreshAllFiles)(newManifest, scopeSourcePath, {
+                force: options.force,
+                benchmarkCollector: collector,
+            });
             // Update the in-memory manifest for this scope
             if (ConfigManager.isMultiScopeManifest(curManifest)) {
                 curManifest[scope] = newManifest;
@@ -182,16 +262,27 @@ const syncManifest = async (scope) => {
             }
         }
         else {
-            // Sync all scopes if manifest has multiple scopes
-            if (ConfigManager.isMultiScopeManifest(curManifest)) {
-                // Multiple scopes detected
+            // Sync all scopes. Prefer the declared-scopes list (config.scopes) over
+            // the persisted manifest keys — the manifest may contain stale undeclared
+            // scopes that leaked in before the whitelist gate existed.
+            var childOptions = {
+                force: options.force,
+                _benchmarkCollector: collector,
+            };
+            if (declaredScopes.length > 0) {
+                for (var d = 0; d < declaredScopes.length; d++) {
+                    await (0, exports.syncManifest)(declaredScopes[d], childOptions);
+                }
+            }
+            else if (ConfigManager.isMultiScopeManifest(curManifest)) {
+                // No declared scopes — fall back to the persisted manifest's scopes.
                 for (const scopeName of Object.keys(curManifest)) {
-                    await (0, exports.syncManifest)(scopeName);
+                    await (0, exports.syncManifest)(scopeName, childOptions);
                 }
             }
             else if (curManifest.scope) {
                 // Single scope manifest
-                await (0, exports.syncManifest)(curManifest.scope);
+                await (0, exports.syncManifest)(curManifest.scope, childOptions);
             }
         }
     }
@@ -203,6 +294,12 @@ const syncManifest = async (scope) => {
             message = String(e);
         Logger_1.logger.error("Refresh failed: " + message);
     }
+    finally {
+        if (isBenchmarkOwner && collector) {
+            (0, snClient_1.setBenchmarkSink)(null);
+            Logger_1.logger.info(collector.formatSummary());
+        }
+    }
 };
 exports.syncManifest = syncManifest;
 const markFileMissing = (missingObj) => (table) => (recordId) => (file) => {
@@ -274,6 +371,158 @@ const findMissingFiles = async (manifest, sourcePath) => {
     return missing;
 };
 exports.findMissingFiles = findMissingFiles;
+// Chunk bulkDownload by table to stay under ServiceNow's 10 MB REST payload cap.
+// A single unchunked call 500s on large scopes (e.g. x_cadso_automate at ~29 MB).
+// Must mirror the chunk size used by allScopesCommands.ts (watch path) so behaviour
+// is consistent across `refresh` and `watch`.
+const BULK_DOWNLOAD_TABLE_CHUNK_SIZE = 5;
+/**
+ * Builds a MissingFileTableMap containing EVERY file in the manifest — ignores
+ * local disk state. Used by `sinc refresh` to pull instance-side edits down.
+ */
+const buildAllFilesMap = (manifest) => {
+    const result = {};
+    const { tables } = manifest;
+    const tableNames = Object.keys(tables);
+    for (var t = 0; t < tableNames.length; t++) {
+        var tableName = tableNames[t];
+        var records = tables[tableName].records;
+        var recNames = Object.keys(records);
+        if (recNames.length === 0)
+            continue;
+        var recMap = {};
+        for (var r = 0; r < recNames.length; r++) {
+            var rec = records[recNames[r]];
+            if (!rec.files || rec.files.length === 0)
+                continue;
+            // Strip any content that may be lingering on manifest file entries; the
+            // bulkDownload endpoint only needs name + type to resolve each field.
+            recMap[rec.sys_id] = rec.files.map(function (f) {
+                return { name: f.name, type: f.type };
+            });
+        }
+        if (Object.keys(recMap).length > 0)
+            result[tableName] = recMap;
+    }
+    return result;
+};
+/**
+ * Refreshes local files against the ServiceNow instance for every file in the
+ * given manifest. Unlike `processMissingFiles` (which only writes files absent
+ * from disk), this walks ALL manifest files, fetches their current content from
+ * the instance, and writes when content differs.
+ *
+ * @param options.force — when true, always overwrite local files even if their
+ * content matches the instance. Use for deliberate "reset local to instance".
+ */
+const refreshAllFiles = async (newManifest, sourcePath, options = {}) => {
+    try {
+        const allFiles = buildAllFilesMap(newManifest);
+        const tableNames = Object.keys(allFiles);
+        if (tableNames.length === 0)
+            return;
+        FileLogger_1.fileLogger.debug("Refreshing file content for " + tableNames.length + " tables (force=" + !!options.force + ")");
+        const { tableOptions = {} } = ConfigManager.getConfig();
+        const client = (0, snClient_1.defaultClient)();
+        const totalChunks = Math.ceil(tableNames.length / BULK_DOWNLOAD_TABLE_CHUNK_SIZE);
+        const filesToProcess = {};
+        for (var i = 0; i < tableNames.length; i += BULK_DOWNLOAD_TABLE_CHUNK_SIZE) {
+            const chunkTableNames = tableNames.slice(i, i + BULK_DOWNLOAD_TABLE_CHUNK_SIZE);
+            const chunkMissing = {};
+            for (var j = 0; j < chunkTableNames.length; j++) {
+                chunkMissing[chunkTableNames[j]] = allFiles[chunkTableNames[j]];
+            }
+            const batchNum = Math.floor(i / BULK_DOWNLOAD_TABLE_CHUNK_SIZE) + 1;
+            FileLogger_1.fileLogger.debug("Refresh download batch " + batchNum + "/" + totalChunks +
+                " (" + chunkTableNames.length + " tables): " + chunkTableNames.join(", "));
+            const chunkResult = await (0, snClient_1.unwrapSNResponse)(client.getMissingFiles(chunkMissing, tableOptions));
+            for (var tableName in chunkResult) {
+                filesToProcess[tableName] = chunkResult[tableName];
+            }
+        }
+        var basePath = sourcePath || ConfigManager.getSourcePath();
+        var recordCount = countRecordsInTables(filesToProcess);
+        var progress = createScopeProgress(Logger_1.logger.getLogLevel(), {
+            scope: newManifest.scope || "default",
+            total: recordCount,
+        });
+        var writtenCount = 0;
+        var unchangedCount = 0;
+        const forceWrite = !!options.force;
+        const forceWriter = fUtils.writeSNFileCurry(false);
+        const processedTableNames = Object.keys(filesToProcess);
+        await (0, genericUtils_1.processBatched)(processedTableNames, constants_1.CONCURRENCY_TABLES, async function (tableName) {
+            var tablePath = path_1.default.join(basePath, tableName);
+            var recs = filesToProcess[tableName].records;
+            var recKeys = Object.keys(recs);
+            await Promise.all(recKeys.map(function (k) {
+                return fUtils.createDirRecursively(path_1.default.join(tablePath, recs[k].name));
+            }));
+            await (0, genericUtils_1.processBatched)(recKeys, constants_1.CONCURRENCY_RECORDS, async function (recKey) {
+                var rec = recs[recKey];
+                var recPath = path_1.default.join(tablePath, rec.name);
+                var results = await (0, genericUtils_1.allSettledBatched)(rec.files, constants_1.CONCURRENCY_FILES, async function (file) {
+                    if (forceWrite) {
+                        await forceWriter(file, recPath);
+                        return true;
+                    }
+                    return fUtils.writeSNFileIfDifferent(file, recPath);
+                });
+                var anyChanged = false;
+                for (var f = 0; f < results.length; f++) {
+                    var res = results[f];
+                    if (res.status === "rejected") {
+                        FileLogger_1.fileLogger.error("File write failed: " + res.reason);
+                        continue;
+                    }
+                    if (res.value) {
+                        anyChanged = true;
+                        writtenCount++;
+                    }
+                    else {
+                        unchangedCount++;
+                    }
+                }
+                // Only touch metaData when at least one file in the record actually
+                // changed. Avoids rewriting _lastUpdatedOn for records that were
+                // already in sync with the instance.
+                if (anyChanged || forceWrite) {
+                    const metadataFile = {
+                        name: "metaData",
+                        type: "json",
+                        content: JSON.stringify({ _lastUpdatedOn: new Date().toISOString() }, null, 2),
+                    };
+                    await forceWriter(metadataFile, recPath);
+                }
+                // Strip content from manifest entries to keep memory bounded.
+                rec.files = rec.files.map(function (file) {
+                    var copy = Object.assign({}, file);
+                    delete copy.content;
+                    return copy;
+                });
+                progress.tick();
+            });
+        });
+        FileLogger_1.fileLogger.debug("Refresh complete: " + writtenCount + " written, " + unchangedCount + " unchanged");
+        if (writtenCount > 0) {
+            Logger_1.logger.info("Refreshed " + writtenCount + " file(s) from instance" +
+                (unchangedCount > 0 ? " (" + unchangedCount + " already in sync)" : ""));
+        }
+        else {
+            Logger_1.logger.debug("No file changes detected from instance (" + unchangedCount + " checked)");
+        }
+        if (options.benchmarkCollector) {
+            options.benchmarkCollector.endScope(writtenCount, unchangedCount);
+        }
+    }
+    catch (e) {
+        if (options.benchmarkCollector) {
+            options.benchmarkCollector.endScope(0, 0);
+        }
+        throw e;
+    }
+};
+exports.refreshAllFiles = refreshAllFiles;
 const processMissingFiles = async (newManifest, sourcePath) => {
     try {
         const missing = await (0, exports.findMissingFiles)(newManifest, sourcePath);
@@ -283,13 +532,32 @@ const processMissingFiles = async (newManifest, sourcePath) => {
         FileLogger_1.fileLogger.debug("Downloading missing files from " + missingTableCount + " tables");
         const { tableOptions = {} } = ConfigManager.getConfig();
         const client = (0, snClient_1.defaultClient)();
-        const filesToProcess = await (0, snClient_1.unwrapSNResponse)(client.getMissingFiles(missing, tableOptions));
+        // Chunk the bulkDownload request: ServiceNow rejects REST payloads > 10 MB,
+        // so send table batches and merge the results before processing.
+        const tableNames = Object.keys(missing);
+        const totalChunks = Math.ceil(tableNames.length / BULK_DOWNLOAD_TABLE_CHUNK_SIZE);
+        const filesToProcess = {};
+        for (var i = 0; i < tableNames.length; i += BULK_DOWNLOAD_TABLE_CHUNK_SIZE) {
+            const chunkTableNames = tableNames.slice(i, i + BULK_DOWNLOAD_TABLE_CHUNK_SIZE);
+            const chunkMissing = {};
+            for (var j = 0; j < chunkTableNames.length; j++) {
+                chunkMissing[chunkTableNames[j]] = missing[chunkTableNames[j]];
+            }
+            const batchNum = Math.floor(i / BULK_DOWNLOAD_TABLE_CHUNK_SIZE) + 1;
+            FileLogger_1.fileLogger.debug("Bulk download batch " + batchNum + "/" + totalChunks +
+                " (" + chunkTableNames.length + " tables): " + chunkTableNames.join(", "));
+            const chunkResult = await (0, snClient_1.unwrapSNResponse)(client.getMissingFiles(chunkMissing, tableOptions));
+            // Chunks are partitioned by table key, so merging is a simple assign.
+            for (var tableName in chunkResult) {
+                filesToProcess[tableName] = chunkResult[tableName];
+            }
+        }
         var recordCount = countRecordsInTables(filesToProcess);
         var progress = createScopeProgress(Logger_1.logger.getLogLevel(), {
             scope: newManifest.scope || "default",
             total: recordCount,
         });
-        await processTablesInManifest(filesToProcess, false, sourcePath, progress.tick);
+        await processTablesInManifest(filesToProcess, false, sourcePath, progress.tick, newManifest.scope);
     }
     catch (e) {
         throw e;

package/dist/benchmark.js

@@ -0,0 +1,104 @@
+"use strict";
+/**
+ * Opt-in benchmark collector for `sinc refresh`. Wired into snClient via
+ * setBenchmarkSink — when null (the default), there is zero overhead.
+ *
+ * PR #36 changed refresh from "download files absent from disk" to "bulk-download
+ * every manifest file and compare before writing". That shifted the request
+ * profile silently. This collector surfaces the numbers so regressions are
+ * visible.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BenchmarkCollector = void 0;
+class BenchmarkCollector {
+    httpSamples = [];
+    scopeSamples = [];
+    currentScope = null;
+    recordHttp(sample) {
+        this.httpSamples.push(sample);
+    }
+    startScope(scopeName) {
+        this.currentScope = {
+            name: scopeName,
+            startedAt: Date.now(),
+            httpStart: this.httpSamples.length,
+            bytesStart: this.totalBytes(),
+        };
+    }
+    endScope(filesWritten, filesUnchanged) {
+        if (!this.currentScope)
+            return;
+        var scope = this.currentScope;
+        this.scopeSamples.push({
+            scopeName: scope.name,
+            wallTimeMs: Date.now() - scope.startedAt,
+            httpRequests: this.httpSamples.length - scope.httpStart,
+            filesWritten: filesWritten,
+            filesUnchanged: filesUnchanged,
+            totalResponseBytes: this.totalBytes() - scope.bytesStart,
+        });
+        this.currentScope = null;
+    }
+    getHttpSamples() {
+        return this.httpSamples.slice();
+    }
+    getScopeSamples() {
+        return this.scopeSamples.slice();
+    }
+    totalBytes() {
+        var total = 0;
+        for (var i = 0; i < this.httpSamples.length; i++) {
+            total += this.httpSamples[i].responseBytes;
+        }
+        return total;
+    }
+    formatSummary() {
+        var lines = [];
+        lines.push("");
+        lines.push("=".repeat(72));
+        lines.push("Refresh Benchmark");
+        lines.push("=".repeat(72));
+        if (this.httpSamples.length === 0) {
+            lines.push("(no samples recorded)");
+            return lines.join("\n");
+        }
+        var latencies = this.httpSamples
+            .map(function (s) { return s.durationMs; })
+            .sort(function (a, b) { return a - b; });
+        var p50 = percentile(latencies, 0.5);
+        var p95 = percentile(latencies, 0.95);
+        var max = latencies[latencies.length - 1];
+        var totalBytes = this.totalBytes();
+        lines.push("Overall: " + this.httpSamples.length + " HTTP requests, " +
+            formatBytes(totalBytes) + " received");
+        lines.push("Latency: p50 " + p50 + "ms | p95 " + p95 + "ms | max " + max + "ms");
+        if (this.scopeSamples.length > 0) {
+            lines.push("");
+            lines.push("Per-scope:");
+            for (var i = 0; i < this.scopeSamples.length; i++) {
+                var s = this.scopeSamples[i];
+                lines.push("  " + s.scopeName + ": " +
+                    s.wallTimeMs + "ms wall, " +
+                    s.httpRequests + " req, " +
+                    formatBytes(s.totalResponseBytes) + ", " +
+                    s.filesWritten + " written / " + s.filesUnchanged + " unchanged");
+            }
+        }
+        lines.push("=".repeat(72));
+        return lines.join("\n");
+    }
+}
+exports.BenchmarkCollector = BenchmarkCollector;
+function percentile(sortedAsc, p) {
+    if (sortedAsc.length === 0)
+        return 0;
+    var idx = Math.min(sortedAsc.length - 1, Math.floor(sortedAsc.length * p));
+    return sortedAsc[idx];
+}
+function formatBytes(n) {
+    if (n < 1024)
+        return n + "B";
+    if (n < 1024 * 1024)
+        return (n / 1024).toFixed(1) + "KB";
+    return (n / (1024 * 1024)).toFixed(2) + "MB";
+}

package/dist/commander.js

@@ -50,7 +50,31 @@ async function initCommands() {
     }, async (args) => {
         await (0, allScopesCommands_1.watchAllScopesCommand)(args);
     })
-        .command(["refresh", "r"], "Refresh Manifest and download new files since last refresh", sharedOptions, commands_1.refreshCommand)
+        .command(["refresh", "r"], "Pull latest manifest and file contents from the ServiceNow instance", (cmdArgs) => {
+        cmdArgs.options({
+            ...sharedOptions,
+            force: {
+                alias: "f",
+                type: "boolean",
+                default: false,
+                describe: "Overwrite local files even when content matches the instance",
+            },
+            scope: {
+                alias: "s",
+                type: "string",
+                describe: "Refresh a single scope (default: all declared scopes)",
+            },
+            benchmark: {
+                alias: "b",
+                type: "boolean",
+                default: false,
+                describe: "Log per-scope and aggregate HTTP latency, bytes, and file counts",
+            },
+        });
+        return cmdArgs;
+    }, async (args) => {
+        await (0, commands_1.refreshCommand)(args);
+    })
         .command(["push [target]"], "[DESTRUCTIVE] Push all files from current local files to ServiceNow instance.", (cmdArgs) => {
         cmdArgs.options({
             ...sharedOptions,

package/dist/commands.js

@@ -65,8 +65,11 @@ async function refreshCommand(args, log = true) {
     try {
         if (!log)
             setLogLevel({ logLevel: "warn" });
-        FileLogger_1.fileLogger.debug("Syncing manifest from instance");
-        await AppUtils.syncManifest();
+        FileLogger_1.fileLogger.debug("Syncing manifest from instance (force=" + !!args.force + ", benchmark=" + !!args.benchmark + ")");
+        await AppUtils.syncManifest(args.scope, {
+            force: !!args.force,
+            benchmark: !!args.benchmark,
+        });
         Logger_1.logger.success("Refresh complete!");
         setLogLevel(args);
     }