@snutils/snu 0.1.10 → 0.2.1

package/dist/server/dispatcher.js

@@ -33,8 +33,10 @@ 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");
@@ -42,6 +44,49 @@ 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'];
+// Human labels + the environment variable each gate is *actually* read from in
+// config.ts. Deriving the variable name from the camelCase gate key produces
+// SNU_ALLOW_RESTREQUEST, which nothing reads, so an agent told to set it hits
+// the same wall twice and starts looking for a way around the gate. Keep these
+// tables in step with resolveStandaloneConfig().
+const GATE_LABELS = {
+    backgroundScripts: 'Background Scripts',
+    deleteRecords: 'Delete Records',
+    createArtifacts: 'Create Artifacts',
+    browserDebugger: 'Browser Debugger',
+    restRequest: 'REST Request API',
+};
+const REST_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
+// Mirrors codeForRest() in the VS Code agent so both hosts report the same
+// code for the same HTTP failure.
+function codeForRestStatus(status, message) {
+    if (status === 404)
+        return 'E_NOT_FOUND';
+    if (status === 409)
+        return 'E_REFERENCE_INTEGRITY';
+    if (status === 401 || status === 403)
+        return 'E_ACL';
+    const lower = (message || '').toLowerCase();
+    if (lower.includes('cannot delete') || lower.includes('referenc') || lower.includes('cascade')) {
+        return 'E_REFERENCE_INTEGRITY';
+    }
+    return 'E_COMMAND_FAILED';
+}
+const GATE_ENV_VARS = {
+    backgroundScripts: 'SNU_ALLOW_BACKGROUND_SCRIPTS',
+    deleteRecords: 'SNU_ALLOW_DELETE_RECORDS',
+    createArtifacts: 'SNU_ALLOW_CREATE_ARTIFACTS',
+    browserDebugger: 'SNU_ALLOW_BROWSER_DEBUGGER',
+    restRequest: 'SNU_ALLOW_REST_REQUEST',
+};
+// 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' },
@@ -141,6 +186,61 @@ function resolveFieldExtension(tableName, fieldName, cwd) {
         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;
@@ -174,6 +274,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 });
@@ -384,10 +611,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);
@@ -397,16 +627,21 @@ class StandaloneDispatcher {
             for (const gateName of policy.gates) {
                 // A. Check Host Gate (Fail-closed standalone authority)
                 if (!this.config.gates[gateName]) {
-                    const label = gateName === 'backgroundScripts' ? 'Background Scripts' : gateName === 'deleteRecords' ? 'Delete Records' : gateName;
-                    throw Object.assign(new Error(`${label} is disabled in standalone host config. Pass --allow-${gateName.replace(/[A-Z]/g, (l) => '-' + l.toLowerCase())} or set SNU_ALLOW_${gateName.toUpperCase()}=1.`), { code: 'E_DISABLED' });
+                    const label = GATE_LABELS[gateName] || gateName;
+                    const envVar = GATE_ENV_VARS[gateName];
+                    throw Object.assign(new Error(`${label} is disabled in this snu host config, so ${req.command} cannot run. ` +
+                        `Turn it on with ${envVar}=1 in the MCP server's env block, or "${gateName}": true in ~/.sn-scriptsync/settings.json, then restart snu. ` +
+                        `This is the user's decision to make: ask them to enable it rather than routing around it through the browser UI.`), { code: 'E_DISABLED', details: { gate: gateName, envVar, source: 'host' } });
                 }
                 // B. Check Helper Instance Gate (if instanceSecurityGates capability is present)
                 const helperState = this.ws.getHelperState();
                 if (helperState.capabilities?.instanceSecurityGates && instanceOrigin) {
                     const helperGateMode = this.ws.getInstanceGate(instanceUrl, gateName);
                     if (helperGateMode === 'off' || helperGateMode === false) {
-                        const label = gateName === 'backgroundScripts' ? 'Background Scripts' : gateName === 'deleteRecords' ? 'Delete Records' : gateName;
-                        throw Object.assign(new Error(`This instance (${instanceOrigin}) does not permit ${label.toLowerCase()} in SN Utils helper.`), { code: 'E_DISABLED' });
+                        const label = GATE_LABELS[gateName] || gateName;
+                        throw Object.assign(new Error(`This instance (${instanceOrigin}) does not permit ${label} in the SN Utils helper, so ${req.command} cannot run. ` +
+                            `The user can turn it on in the helper tab's Agent Access tab for this instance. ` +
+                            `This is the user's decision to make: ask them to enable it rather than routing around it through the browser UI.`), { code: 'E_DISABLED', details: { gate: gateName, instanceOrigin, source: 'instance' } });
                     }
                 }
             }
@@ -699,6 +934,61 @@ class StandaloneDispatcher {
                     },
                 };
             }
+            // Create Record (plain data row). Same insert as create_artifact minus the
+            // name requirement and the local _map.json tracking, which only makes
+            // sense for artifacts that have a file in the workspace.
+            if (req.command === 'create_record') {
+                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 param "table" (must be alphanumeric/underscore)'), { code: 'E_INVALID_PARAMS' });
+                }
+                const table = rawTable.trim();
+                const fields = req.params?.fields;
+                if (!fields || typeof fields !== 'object' || Array.isArray(fields) || Object.keys(fields).length === 0) {
+                    throw Object.assign(new Error('Missing required param "fields": provide at least one field value for the new record'), { code: 'E_INVALID_PARAMS' });
+                }
+                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: 'POST',
+                    body: fields,
+                    queryParams: { sysparm_display_value: 'false', sysparm_exclude_reference_link: 'true' },
+                    instance: inst.settings,
+                    appName: 'SN Utils CLI',
+                });
+                const res = await pendingPromise;
+                if (res.success === false) {
+                    const message = res.error || `Failed to create a record on ${table}`;
+                    throw Object.assign(new Error(message), {
+                        code: res.code || codeForRestStatus(res.status, message),
+                        details: { status: res.status, detail: res.detail ?? null },
+                    });
+                }
+                // POST /api/now/table returns the inserted row, so the write is already
+                // verified: no follow-up get_record needed.
+                const record = res.data?.result ?? null;
+                const readField = (name) => {
+                    const value = record?.[name];
+                    if (value && typeof value === 'object')
+                        return String(value.value ?? value.display_value ?? '');
+                    return value === undefined || value === null ? '' : String(value);
+                };
+                return {
+                    id: req.id,
+                    command: req.command,
+                    status: 'success',
+                    timestamp: Date.now(),
+                    result: {
+                        created: true,
+                        table,
+                        sys_id: readField('sys_id'),
+                        name: readField('number') || readField('name') || readField('sys_name') || readField('short_description'),
+                        record,
+                    },
+                };
+            }
             // Schema Metadata
             if (req.command === 'get_table_metadata') {
                 const table = req.params?.table;
@@ -833,29 +1123,16 @@ class StandaloneDispatcher {
                         warnings.push(`Could not resolve map path for ${scope}/${table}: ${e?.message || e}`);
                         continue;
                     }
-                    let nameToSysId = {};
-                    if (fs.existsSync(mapPath)) {
-                        try {
-                            nameToSysId = JSON.parse(fs.readFileSync(mapPath, 'utf8')) || {};
-                        }
-                        catch { }
-                    }
-                    let cleanName = name.replace(/[^a-z0-9._\-+]+/gi, '').replace(/\./g, '-') || sysId;
-                    const existingKey = Object.keys(nameToSysId).find((k) => nameToSysId[k] === sysId);
-                    if (existingKey) {
-                        cleanName = existingKey;
-                    }
-                    else if (nameToSysId[cleanName] && nameToSysId[cleanName] !== sysId) {
-                        cleanName = `${cleanName}-${sysId.slice(0, 2)}${sysId.slice(-2)}`.toUpperCase();
-                    }
-                    nameToSysId[cleanName] = sysId;
+                    const { cleanName, renamedTo, map: nameToSysId } = resolveMappedFileName(mapPath, name, sysId);
                     try {
-                        fs.mkdirSync(path.dirname(mapPath), { recursive: true });
-                        fs.writeFileSync(mapPath, JSON.stringify(nameToSysId, null, 4), 'utf8');
+                        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');
@@ -940,6 +1217,47 @@ class StandaloneDispatcher {
                     },
                 };
             }
+            // Generic REST passthrough. The escape hatch the typed commands are built
+            // on: the browser helper's agentRestApi action has always accepted every
+            // method plus a body, so this needs no extension-side change. Gating is
+            // handled above by getCommandPolicy (GET open, POST/PUT/PATCH behind
+            // restRequest, DELETE behind deleteRecords).
+            if (req.command === 'rest_request') {
+                const endpoint = req.params?.endpoint;
+                if (!endpoint || typeof endpoint !== 'string' || !endpoint.startsWith('/')) {
+                    throw Object.assign(new Error("Missing/invalid 'endpoint' (must be an instance-relative path beginning with '/', e.g. /api/now/table/incident)"), { code: 'E_INVALID_PARAMS' });
+                }
+                const method = String(req.params?.method || 'GET').toUpperCase();
+                if (!REST_METHODS.includes(method)) {
+                    throw Object.assign(new Error(`Invalid method. Must be one of: ${REST_METHODS.join(', ')}`), { code: 'E_INVALID_PARAMS' });
+                }
+                const pendingPromise = this.pending.register({ id: correlationId, command: req.command, timeoutMs: 70_000 });
+                this.ws.sendToBrowser({
+                    action: 'agentRestApi',
+                    agentRequestId: correlationId,
+                    endpoint,
+                    method,
+                    body: req.params?.body,
+                    queryParams: req.params?.queryParams && typeof req.params.queryParams === 'object' ? req.params.queryParams : undefined,
+                    instance: inst.settings,
+                    appName: 'SN Utils CLI',
+                });
+                const res = await pendingPromise;
+                if (res.success === false) {
+                    const message = res.error || 'REST request failed';
+                    throw Object.assign(new Error(message), {
+                        code: res.code || codeForRestStatus(res.status, message),
+                        details: { status: res.status, detail: res.detail ?? null },
+                    });
+                }
+                return {
+                    id: req.id,
+                    command: req.command,
+                    status: 'success',
+                    timestamp: Date.now(),
+                    result: { status: res.status, data: res.data },
+                };
+            }
             // Browser Form & UI Actions
             if (['get_form_state', 'set_field', 'run_ui_action', 'navigate', 'take_screenshot'].includes(req.command)) {
                 const actionMap = {