@snutils/snu 0.1.9 → 0.2.0

package/dist/server/dispatcher.js

@@ -33,14 +33,179 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.StandaloneDispatcher = void 0;
+exports.StandaloneDispatcher = exports.HELPER_CONNECT_GUIDANCE = void 0;
+exports.resolveMappedFileName = resolveMappedFileName;
 const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const crypto = __importStar(require("crypto"));
 const pendingRegistry_js_1 = require("./pendingRegistry.js");
 const policy_js_1 = require("./policy.js");
 const config_js_1 = require("./config.js");
 const canonical_js_1 = require("./canonical.js");
+const FOLDERRECORDTABLES = ['sp_widget', 'sp_header_footer', 'sys_ui_page'];
+// Steps a user must take to (re)connect the browser helper tab. Rendered by
+// the CLI as a friendly block and relayed verbatim by the MCP server so
+// agents guide the user instead of reporting a raw error.
+exports.HELPER_CONNECT_GUIDANCE = [
+    'Open your ServiceNow instance in the browser (with the SN Utils extension installed).',
+    'On that page, type /token in the SN Utils slash palette: this opens the helper tab and connects it.',
+    'Keep the helper tab open, then retry.',
+];
+const FIELDTYPES = {
+    script: { extension: '.js' },
+    script_plain: { extension: '.js' },
+    script_server: { extension: '.js' },
+    script_client: { extension: '.js' },
+    email_script: { extension: '.js' },
+    html_script: { extension: '.html' },
+    xml: { extension: '.xml' },
+    html: { extension: '.html' },
+    html_template: { extension: '.html' },
+    template: { extension: '.html' },
+    json: { extension: '.json' },
+    css: { extension: '.scss' },
+    condition_string: { extension: '.js' },
+    expression: { extension: '.js' },
+    graphql_schema: { extension: '.graphql' },
+    json_translations: { extension: '.json' },
+    translated_html: { extension: '.html' },
+    string: { extension: '.txt' },
+};
+function sanitizePathComponent(component) {
+    if (typeof component !== 'string') {
+        throw new Error('Path component is not a string');
+    }
+    const value = component.trim();
+    if (!value || value === '.' || value === '..') {
+        throw new Error(`Unsafe path component ${JSON.stringify(component)}`);
+    }
+    if (/[\\/\0]/.test(value) || /^[A-Za-z]:/.test(value) || value.startsWith('~')) {
+        throw new Error(`Unsafe path component ${JSON.stringify(component)}`);
+    }
+    return value;
+}
+function safeJoinUnderRoot(root, ...components) {
+    if (!root) {
+        throw new Error('No root path provided');
+    }
+    const resolvedRoot = path.resolve(root);
+    const resolved = path.resolve(resolvedRoot, ...components.map(sanitizePathComponent));
+    const rel = path.relative(resolvedRoot, resolved);
+    if (rel === '..' || rel.startsWith('..' + path.sep) || path.isAbsolute(rel)) {
+        throw new Error(`Path escapes root: ${resolved}`);
+    }
+    return resolved;
+}
+let metaDataRelationsCache = null;
+function getMetaDataRelations(cwd) {
+    if (!metaDataRelationsCache) {
+        const candidates = [
+            path.resolve(cwd, 'resources', 'metaDataRelations.json'),
+            path.resolve(__dirname, '../../../../resources/metaDataRelations.json'),
+            path.resolve(__dirname, '../../../resources/metaDataRelations.json'),
+        ];
+        for (const c of candidates) {
+            if (fs.existsSync(c)) {
+                try {
+                    metaDataRelationsCache = JSON.parse(fs.readFileSync(c, 'utf8'));
+                    break;
+                }
+                catch { }
+            }
+        }
+    }
+    return metaDataRelationsCache;
+}
+function resolveTableCodeFields(tableName, cwd) {
+    const meta = getMetaDataRelations(cwd);
+    const fields = meta?.tableFields?.[tableName]?.codeFields;
+    if (fields && typeof fields === 'object') {
+        const keys = Object.keys(fields).filter((k) => !k.startsWith('_'));
+        if (keys.length > 0)
+            return keys;
+    }
+    return ['script'];
+}
+function resolveFieldExtension(tableName, fieldName, cwd) {
+    const meta = getMetaDataRelations(cwd);
+    let fieldType = 'script';
+    try {
+        fieldType = meta?.tableFields?.[tableName]?.codeFields?.[fieldName]?.type || fieldName;
+    }
+    catch { }
+    let ext = FIELDTYPES[fieldType]?.extension;
+    if (fieldType.includes('xml'))
+        ext = '.xml';
+    else if (fieldType.includes('html'))
+        ext = '.html';
+    else if (fieldType.includes('json'))
+        ext = '.json';
+    else if (fieldType.includes('css') || fieldType === 'properties' || fieldName === 'css')
+        ext = '.scss';
+    else if (fieldType.includes('string') || fieldType === 'conditions')
+        ext = '.txt';
+    else if (fieldType.includes('graphql'))
+        ext = '.graphql';
+    else if (!ext)
+        ext = '.js';
+    return ext;
+}
+// Canonical filename resolution against a folder's _map.json, shared by
+// pull_records and browser save pushes. Mirrors the VS Code extension: an
+// existing mapping for the sys_id wins (so a record renamed on the instance
+// keeps its stable local filename, reported via `renamedTo`), and a name
+// collision with another sys_id gets a short sys_id suffix.
+function resolveMappedFileName(mapPath, rawName, sysId) {
+    let nameToSysId = {};
+    if (fs.existsSync(mapPath)) {
+        try {
+            nameToSysId = JSON.parse(fs.readFileSync(mapPath, 'utf8')) || {};
+        }
+        catch { }
+    }
+    const computed = String(rawName).replace(/[^a-z0-9._\-+]+/gi, '').replace(/\./g, '-') || sysId;
+    let cleanName = computed;
+    let renamedTo;
+    const existingKey = Object.keys(nameToSysId).find((k) => nameToSysId[k] === sysId);
+    if (existingKey) {
+        cleanName = existingKey;
+        if (existingKey !== computed)
+            renamedTo = computed;
+    }
+    else if (nameToSysId[cleanName] && nameToSysId[cleanName] !== sysId) {
+        cleanName = cleanName + ('-' + sysId.slice(0, 2) + sysId.slice(-2)).toUpperCase();
+    }
+    nameToSysId[cleanName] = sysId;
+    return { cleanName, renamedTo, map: nameToSysId };
+}
+function writeMapFile(mapPath, map) {
+    fs.mkdirSync(path.dirname(mapPath), { recursive: true });
+    fs.writeFileSync(mapPath, JSON.stringify(map, null, 4), 'utf8');
+}
+// Extension for a browser save push, derived from the payload's fieldType the
+// same way the VS Code extension does it (saveFieldAsFile).
+function extensionForBrowserSave(fieldType, fieldName, tableName, cleanName) {
+    let ext = FIELDTYPES[fieldType]?.extension;
+    if (fieldType.includes('xml'))
+        ext = '.xml';
+    else if (fieldType.includes('html'))
+        ext = '.html';
+    else if (fieldType.includes('json'))
+        ext = '.json';
+    else if (fieldType.includes('css') || fieldType === 'properties' || fieldName === 'css')
+        ext = '.scss';
+    else if (cleanName.lastIndexOf('-') > -1 && tableName === 'ecc_agent_script_file') {
+        const suffix = cleanName.substring(cleanName.lastIndexOf('-') + 1);
+        if (suffix.length < 5)
+            ext = '.' + suffix;
+    }
+    else if (fieldType.includes('string') || fieldType === 'conditions')
+        ext = '.txt';
+    else if (fieldName === 'PowerShell')
+        ext = '.ps1';
+    return ext || '.js';
+}
 class StandaloneDispatcher {
     cwd;
     ws;
@@ -74,6 +239,133 @@ class StandaloneDispatcher {
         }
         return null;
     }
+    // Browser save-icon pushes (action: 'saveFieldAsFile') arrive on the port
+    // 1978 socket whether VS Code or this daemon is listening; VS Code writes
+    // the field into the sync workspace, and historically the daemon dropped
+    // the message silently. Mirror the VS Code behavior so a daemon-only setup
+    // still lands pushes on disk. One-way by design: the daemon has no file
+    // watcher, so local edits flow back via agent commands or VS Code.
+    async handleBrowserFieldSave(msg) {
+        const echo = (payload) => {
+            try {
+                this.ws.sendToBrowser(payload);
+            }
+            catch { }
+        };
+        try {
+            const instanceName = sanitizePathComponent(String(msg?.instance?.name || ''));
+            const table = sanitizePathComponent(String(msg?.table || ''));
+            const sysId = String(msg?.sys_id || '');
+            const rawName = String(msg?.name || '');
+            const field = String(msg?.field || '');
+            const content = typeof msg?.content === 'string' ? msg.content : String(msg?.content ?? '');
+            if (!sysId || !field)
+                throw new Error('Save push is missing sys_id or field');
+            // Refuse to scatter files when the daemon was clearly started outside a
+            // sync workspace.
+            const resolvedCwd = path.resolve(this.cwd);
+            if (resolvedCwd === path.resolve(os.homedir()) || resolvedCwd === path.parse(resolvedCwd).root) {
+                console.warn(`[snu] Ignored a save push from the browser: ${resolvedCwd} does not look like a ScriptSync workspace. Start snu from your sync folder.`);
+                return;
+            }
+            const scope = await this.resolveScopeFolderForSave(msg, instanceName);
+            // Variable fields arrive as inputs.<var>.script
+            const fieldName = field.split('.').length === 3 ? 'variable-' + field.split('.')[2] : field;
+            const isFolderRecordTable = FOLDERRECORDTABLES.includes(table);
+            const mapPath = safeJoinUnderRoot(this.cwd, instanceName, scope, table, '_map.json');
+            const { cleanName, renamedTo, map } = resolveMappedFileName(mapPath, rawName, sysId);
+            writeMapFile(mapPath, map);
+            if (renamedTo) {
+                console.log(`[snu] Record ${table}/${sysId} is named '${renamedTo}' on the instance but keeps local file name '${cleanName}' (rename tracked in _map.json).`);
+            }
+            const ext = extensionForBrowserSave(String(msg?.fieldType || 'script'), fieldName, table, cleanName);
+            const targetPath = isFolderRecordTable
+                ? safeJoinUnderRoot(this.cwd, instanceName, scope, table, cleanName, `${fieldName}${ext}`)
+                : safeJoinUnderRoot(this.cwd, instanceName, scope, table, `${cleanName}.${fieldName}${ext}`);
+            fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+            fs.writeFileSync(targetPath, content, 'utf8');
+            console.log(`[snu] Saved ${path.relative(this.cwd, targetPath)} (pushed from ${instanceName})`);
+            // Same success echo VS Code sends: the helper tab logs the push as
+            // delivered when it sees contentLength.
+            echo({ ...msg, result: '', contentLength: content.length, send: false });
+        }
+        catch (e) {
+            const message = e?.message || String(e);
+            console.warn('[snu] Failed to save field pushed from browser:', message);
+            echo({ error: `Standalone snu could not save the pushed field: ${message}`, send: false, response: { result: {} } });
+        }
+    }
+    // Resolve the scope folder name for a browser save push. The payload's
+    // `scope` is a sys_scope sys_id ('global' for global, '' when the form has
+    // no sys_scope field). Mirrors the VS Code extension: scopes.json first,
+    // then ask the instance, falling back to no_scope / unknown_scope.
+    async resolveScopeFolderForSave(msg, instanceName) {
+        const scopeVal = typeof msg?.scope === 'string' ? msg.scope.trim() : '';
+        if (scopeVal === 'global')
+            return 'global';
+        if (!scopeVal) {
+            const fromRecord = await this.queryScopeFromInstance(msg, `/api/now/table/${msg.table}/${msg.sys_id}`, { sysparm_fields: 'sys_scope.scope', sysparm_exclude_reference_link: 'true' }, 'sys_scope.scope');
+            return fromRecord || 'no_scope';
+        }
+        if (/^[0-9a-f]{32}$/i.test(scopeVal)) {
+            const scopesPath = path.join(this.cwd, instanceName, 'scopes.json');
+            try {
+                const scopes = JSON.parse(fs.readFileSync(scopesPath, 'utf8')) || {};
+                const hit = Object.keys(scopes).find((k) => scopes[k] === scopeVal);
+                if (hit)
+                    return hit;
+            }
+            catch { }
+            const fromScope = await this.queryScopeFromInstance(msg, `/api/now/table/sys_scope/${scopeVal}`, { sysparm_fields: 'scope' }, 'scope');
+            if (fromScope) {
+                // Best-effort persist name -> sys_id so the next save skips the round-trip.
+                try {
+                    let scopes = {};
+                    try {
+                        scopes = JSON.parse(fs.readFileSync(scopesPath, 'utf8')) || {};
+                    }
+                    catch { }
+                    if (scopes[fromScope] !== scopeVal) {
+                        scopes[fromScope] = scopeVal;
+                        fs.mkdirSync(path.dirname(scopesPath), { recursive: true });
+                        fs.writeFileSync(scopesPath, JSON.stringify(scopes, null, 4), 'utf8');
+                    }
+                }
+                catch { }
+                return fromScope;
+            }
+            return 'unknown_scope';
+        }
+        // Already a scope name (e.g. flow action saves carry the name directly).
+        if (/^[a-z0-9_.\-]+$/i.test(scopeVal))
+            return scopeVal;
+        return 'unknown_scope';
+    }
+    async queryScopeFromInstance(msg, endpoint, queryParams, resultField) {
+        if (!this.ws.hasBrowserClient())
+            return undefined;
+        try {
+            const correlationId = crypto.randomUUID();
+            const pendingPromise = this.pending.register({ id: correlationId, command: 'resolve_scope_for_save', timeoutMs: 15_000 });
+            this.ws.sendToBrowser({
+                action: 'agentRestApi',
+                agentRequestId: correlationId,
+                endpoint,
+                method: 'GET',
+                queryParams,
+                instance: msg.instance,
+                appName: 'SN Utils CLI',
+            });
+            const res = await pendingPromise;
+            if (res?.success === false)
+                return undefined;
+            const value = res?.data?.result?.[resultField];
+            return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
     listInstanceFolders() {
         try {
             const entries = fs.readdirSync(this.cwd, { withFileTypes: true });
@@ -274,7 +566,7 @@ class StandaloneDispatcher {
                     status: 'success',
                     timestamp: Date.now(),
                     result: {
-                        apiVersion: 8,
+                        apiVersion: 9,
                         tier: state.tier,
                         proFeatures: state.proFeatures,
                         cdp: state.cdp,
@@ -284,10 +576,13 @@ class StandaloneDispatcher {
                     },
                 };
             }
-            // Check browser connection for all instance/remote commands
+            // Check browser connection for all instance/remote commands. Not a
+            // failure of the tool: a user-actionable setup state, so ship guidance
+            // steps in details for the CLI and MCP surfaces to render.
             if (!this.ws.hasBrowserClient()) {
-                throw Object.assign(new Error('Browser helper disconnected. Open the SN Utils helper tab via /token in ServiceNow.'), {
+                throw Object.assign(new Error('ServiceNow is not connected: the SN Utils helper tab is not open.'), {
                     code: 'E_BROWSER_DISCONNECTED',
+                    details: { guidance: exports.HELPER_CONNECT_GUIDANCE },
                 });
             }
             const inst = this.resolveInstance(req.instance);
@@ -623,6 +918,210 @@ class StandaloneDispatcher {
                     result: res.data?.result || res.data,
                 };
             }
+            // Pull Records / Pull Artifacts
+            if (req.command === 'pull_records' || req.command === 'pull_artifacts') {
+                const rawTable = req.params?.table;
+                if (!rawTable || typeof rawTable !== 'string' || !/^[a-zA-Z0-9_]+$/.test(rawTable.trim())) {
+                    throw Object.assign(new Error('Missing or invalid required param "table" (must be alphanumeric/underscore)'), { code: 'E_INVALID_PARAMS' });
+                }
+                const table = rawTable.trim();
+                let limit = 50;
+                if (req.params?.limit !== undefined) {
+                    if (typeof req.params.limit !== 'number' || !Number.isInteger(req.params.limit) || req.params.limit < 1 || req.params.limit > 500) {
+                        throw Object.assign(new Error('Parameter "limit" must be an integer between 1 and 500.'), { code: 'E_INVALID_PARAMS' });
+                    }
+                    limit = req.params.limit;
+                }
+                // Normalize & validate sys_ids
+                const rawIds = [];
+                if (typeof req.params?.sys_id === 'string' && req.params.sys_id.trim()) {
+                    rawIds.push(req.params.sys_id.trim());
+                }
+                if (Array.isArray(req.params?.sys_ids)) {
+                    for (const id of req.params.sys_ids) {
+                        if (typeof id === 'string' && id.trim())
+                            rawIds.push(id.trim());
+                    }
+                }
+                const validHexOrGlobal = /^(?:[0-9a-fA-F]{32}|global)$/;
+                const normalizedIds = Array.from(new Set(rawIds.map((id) => id.toLowerCase())));
+                for (const id of normalizedIds) {
+                    if (!validHexOrGlobal.test(id)) {
+                        throw Object.assign(new Error(`Invalid sys_id "${id}". Must be a 32-character hexadecimal string or 'global'.`), { code: 'E_INVALID_PARAMS' });
+                    }
+                }
+                // Selection combination with ^ (AND)
+                const queryParts = [];
+                if (normalizedIds.length === 1) {
+                    queryParts.push(`sys_id=${normalizedIds[0]}`);
+                }
+                else if (normalizedIds.length > 1) {
+                    queryParts.push(`sys_idIN${normalizedIds.join(',')}`);
+                }
+                if (typeof req.params?.query === 'string' && req.params.query.trim()) {
+                    queryParts.push(req.params.query.trim());
+                }
+                const combinedQuery = queryParts.join('^');
+                // Resolve code fields
+                let codeFields = [];
+                if (Array.isArray(req.params?.fields)) {
+                    codeFields = req.params.fields.filter((f) => typeof f === 'string' && /^[a-zA-Z0-9_]+$/.test(f.trim())).map((f) => f.trim());
+                }
+                else if (typeof req.params?.field === 'string' && /^[a-zA-Z0-9_]+$/.test(req.params.field.trim())) {
+                    codeFields = [req.params.field.trim()];
+                }
+                if (codeFields.length === 0) {
+                    codeFields = resolveTableCodeFields(table, this.cwd);
+                }
+                const displayFields = ['sys_id', 'name', 'sys_name', 'short_description', 'sys_scope', 'sys_scope.scope'];
+                const allRequestedFields = Array.from(new Set([...displayFields, ...codeFields])).join(',');
+                const queryParams = {
+                    sysparm_fields: allRequestedFields,
+                    sysparm_limit: String(limit),
+                    sysparm_display_value: 'false',
+                    sysparm_exclude_reference_link: 'true',
+                    sysparm_no_count: 'true',
+                };
+                if (combinedQuery) {
+                    queryParams.sysparm_query = combinedQuery;
+                }
+                const pendingPromise = this.pending.register({ id: correlationId, command: req.command, timeoutMs: 70_000 });
+                this.ws.sendToBrowser({
+                    action: 'agentRestApi',
+                    agentRequestId: correlationId,
+                    endpoint: `/api/now/table/${table}`,
+                    method: 'GET',
+                    queryParams,
+                    instance: inst.settings,
+                    appName: 'SN Utils CLI',
+                });
+                const res = await pendingPromise;
+                if (res.success === false) {
+                    throw Object.assign(new Error(res.error || 'Failed to pull records'), { code: 'E_COMMAND_FAILED' });
+                }
+                const matchedRecords = Array.isArray(res.data?.result) ? res.data.result : (res.data?.result ? [res.data.result] : []);
+                const isFolderRecordTable = FOLDERRECORDTABLES.includes(table);
+                let filesWritten = 0;
+                let skippedEmpty = 0;
+                const warnings = [];
+                const pulledRecordsList = [];
+                for (const rec of matchedRecords) {
+                    const sysId = typeof rec.sys_id === 'object' ? rec.sys_id.value : String(rec.sys_id || '');
+                    if (!sysId)
+                        continue;
+                    let scope = 'global';
+                    if (rec['sys_scope.scope']) {
+                        scope = String(rec['sys_scope.scope']);
+                    }
+                    else if (rec.sys_scope) {
+                        scope = typeof rec.sys_scope === 'object' ? String(rec.sys_scope.value || rec.sys_scope.display_value || 'global') : String(rec.sys_scope);
+                    }
+                    if (!scope || scope === 'null' || scope === 'undefined')
+                        scope = 'global';
+                    const rawName = rec.name || rec.sys_name || rec.short_description || sysId;
+                    const name = String(rawName).trim();
+                    let mapPath;
+                    try {
+                        mapPath = safeJoinUnderRoot(this.cwd, inst.name, scope, table, '_map.json');
+                    }
+                    catch (e) {
+                        warnings.push(`Could not resolve map path for ${scope}/${table}: ${e?.message || e}`);
+                        continue;
+                    }
+                    const { cleanName, renamedTo, map: nameToSysId } = resolveMappedFileName(mapPath, name, sysId);
+                    try {
+                        writeMapFile(mapPath, nameToSysId);
+                    }
+                    catch (e) {
+                        warnings.push(`Failed to write _map.json at ${mapPath}: ${e?.message || e}`);
+                    }
+                    if (renamedTo) {
+                        warnings.push(`Record ${sysId} is named '${renamedTo}' on the instance but keeps local file name '${cleanName}' (rename tracked in _map.json).`);
+                    }
+                    if (table === 'sp_widget') {
+                        try {
+                            const testUrlsPath = safeJoinUnderRoot(this.cwd, inst.name, scope, table, cleanName, '_test_urls.txt');
+                            if (!fs.existsSync(testUrlsPath)) {
+                                const dispVal = name.toLowerCase().replace(/\s+/g, '_');
+                                const testUrls = [
+                                    `${inst.settings.url}/$sp.do?id=sp-preview&sys_id=${sysId}`,
+                                    `${inst.settings.url}/sp_config?id=${dispVal}`,
+                                    `${inst.settings.url}/sp?id=${dispVal}`,
+                                    `${inst.settings.url}/esc?id=${dispVal}`,
+                                ].join('\n');
+                                fs.mkdirSync(path.dirname(testUrlsPath), { recursive: true });
+                                fs.writeFileSync(testUrlsPath, testUrls, 'utf8');
+                            }
+                        }
+                        catch { }
+                    }
+                    const recordFiles = [];
+                    for (const field of codeFields) {
+                        const ext = resolveFieldExtension(table, field, this.cwd);
+                        let targetPath;
+                        try {
+                            targetPath = isFolderRecordTable
+                                ? safeJoinUnderRoot(this.cwd, inst.name, scope, table, cleanName, `${field}${ext}`)
+                                : safeJoinUnderRoot(this.cwd, inst.name, scope, table, `${cleanName}.${field}${ext}`);
+                        }
+                        catch (e) {
+                            warnings.push(`Unsafe path for ${scope}/${table}/${cleanName}.${field}: ${e?.message || e}`);
+                            continue;
+                        }
+                        const relPath = path.relative(this.cwd, targetPath).replace(/\\/g, '/');
+                        const rawVal = rec[field];
+                        const content = rawVal !== null && rawVal !== undefined ? String(rawVal) : '';
+                        const fileExisted = fs.existsSync(targetPath);
+                        if (content.length > 0) {
+                            try {
+                                fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+                                fs.writeFileSync(targetPath, content, 'utf8');
+                                filesWritten++;
+                                const action = fileExisted ? 'updated' : 'created';
+                                recordFiles.push({ field, path: relPath, bytes: Buffer.byteLength(content, 'utf8'), action });
+                            }
+                            catch (e) {
+                                warnings.push(`Failed to write ${relPath}: ${e?.message || e}`);
+                            }
+                        }
+                        else if (fileExisted) {
+                            try {
+                                fs.writeFileSync(targetPath, '', 'utf8');
+                                filesWritten++;
+                                recordFiles.push({ field, path: relPath, bytes: 0, action: 'cleared' });
+                            }
+                            catch (e) {
+                                warnings.push(`Failed to clear ${relPath}: ${e?.message || e}`);
+                            }
+                        }
+                        else {
+                            skippedEmpty++;
+                            recordFiles.push({ field, path: relPath, bytes: 0, action: 'skipped_empty' });
+                        }
+                    }
+                    pulledRecordsList.push({
+                        sys_id: sysId,
+                        name,
+                        scope,
+                        files: recordFiles,
+                    });
+                }
+                return {
+                    id: req.id,
+                    command: req.command,
+                    status: 'success',
+                    timestamp: Date.now(),
+                    result: {
+                        table,
+                        matchedRecords: matchedRecords.length,
+                        pulledRecords: pulledRecordsList.length,
+                        filesWritten,
+                        skippedEmpty,
+                        warnings,
+                        records: pulledRecordsList,
+                    },
+                };
+            }
             // Browser Form & UI Actions
             if (['get_form_state', 'set_field', 'run_ui_action', 'navigate', 'take_screenshot'].includes(req.command)) {
                 const actionMap = {