@jacebenson/jsn 4.3.8 → 4.3.9

package/src/sdk.js

@@ -4,6 +4,7 @@ import { gunzipSync } from 'node:zlib';
 import { errAuth, errAPI, errNetwork } from './errors.js';
 import { getStringField } from './helpers.js';
 import { getAction, getStepTypes, createAction, updateAction, testAction } from './processflow-actions.js';
+import { readSkippedBaseline, revertSkippedUpdate } from './skipped-update-provider.js';
 
 const DEFAULT_TIMEOUT = 30000;
 
@@ -94,7 +95,8 @@ export class SDKClient {
   }
 
   async request(endpoint, opts = {}) {
-    const { timeout = this.timeout, touchLastSeen = true, ...requestOptions } = opts;
+    const { timeout = this.timeout, readOnly = false, touchLastSeen, ...requestOptions } = opts;
+    if (readOnly && (requestOptions.method || 'GET').toUpperCase() !== 'GET') throw new Error('Read-only SDK requests require GET');
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeout);
 
@@ -110,6 +112,8 @@ export class SDKClient {
       if (this.domain) {
         req.headers.set('X-Now-Domain', this.domain);
       }
+      // readOnly guards the data request, not standard authentication bootstrap.
+      // OAuth refresh and session/GCK negotiation are not instance-record writes.
       await this._setAuth(req);
 
       const resp = await fetch(req);
@@ -125,7 +129,10 @@ export class SDKClient {
 
       // Stamp last_seen on successful API call
       try {
-        if (touchLastSeen && this.authProvider && typeof this.authProvider.touchLastSeen === 'function') {
+        // readOnly suppresses the credential last-seen write unconditionally: a
+        // caller passing touchLastSeen cannot override it (GLOSSARY contract).
+        const shouldTouch = readOnly ? false : (touchLastSeen ?? true);
+        if (shouldTouch && this.authProvider && typeof this.authProvider.touchLastSeen === 'function') {
           this.authProvider.touchLastSeen(this.baseURL);
         }
       } catch { /* non-fatal */ }
@@ -197,6 +204,14 @@ export class SDKClient {
     }
   }
 
+  async getSkippedUpdateBaseline(sysID) {
+    return readSkippedBaseline(this, sysID);
+  }
+
+  async revertSkippedUpdate(sysID, modCount) {
+    return revertSkippedUpdate(this, sysID, modCount);
+  }
+
   async list(table, params = {}, opts = {}) {
     const query = new URLSearchParams(params).toString();
     const endpoint = `${this.baseURL}/api/now/table/${table}${query ? '?' + query : ''}`;
@@ -204,6 +219,22 @@ export class SDKClient {
     return result?.result || [];
   }
 
+  // Strict Table API seam. `list` stays best-effort for legacy callers, but a
+  // 2xx response without a result array is a malformed envelope, not an empty
+  // table. Capture paths use this so an unexpected body becomes an unavailable
+  // source instead of a complete-looking empty inventory.
+  async listStrict(table, params = {}, opts = {}) {
+    const query = new URLSearchParams(params).toString();
+    const endpoint = `${this.baseURL}/api/now/table/${table}${query ? '?' + query : ''}`;
+    const response = await this.request(endpoint, { method: 'GET', ...opts });
+    if (!response || typeof response !== 'object' || !Array.isArray(response.result)) {
+      const error = new Error(`Malformed table response for ${table}: expected a JSON envelope with a result array`);
+      error.code = 'malformed_response';
+      throw error;
+    }
+    return response.result;
+  }
+
   async get(table, sysID) {
     const endpoint = `${this.baseURL}/api/now/table/${table}/${sysID}`;
     const result = await this.request(endpoint, { method: 'GET' });

package/src/skipped-update-provider.js

@@ -0,0 +1,45 @@
+import { errUsage } from './errors.js';
+
+function validateId(id) {
+  if (!/^[0-9a-fA-F]{32}$/.test(id || '')) throw errUsage('A literal 32-hex skipped finding sys_id is required.');
+}
+
+// Contract observed in RevertUpdateVersionAjax.revertToBaseSystem, PDI Australia.
+// Keep read and write separate. No Table API state update can implement revert.
+export async function readSkippedBaseline(sdk, id) {
+  validateId(id);
+  const output = await sdk.executeScript(`(function() {
+    var record = new GlideRecordSecure('sys_upgrade_history_log');
+    if (!record.get('${id}') || !record.canRead()) throw new Error('Finding unavailable');
+    var name = record.getValue('file_name');
+    var storeAppID = GlideappUpdateVersion.getStoreAppID(record);
+    var baseline = storeAppID != null
+      ? GlideappUpdateVersion.getVersion(name, storeAppID, 'sys_store_app', null)
+      : GlideappUpdateVersion.getVersion(name, record.upgrade_history, 'sys_upgrade_history', null);
+    if (!baseline || !baseline.isValidRecord()) throw new Error('No base system version found');
+    gs.print('JSN_SKIPPED_BASE:' + JSON.stringify({sys_id: baseline.getUniqueValue(),
+      payload: baseline.getValue('payload'), source: baseline.getValue('source'),
+      source_table: baseline.getValue('source_table')}));
+  })();`, 'global');
+  const match = output.match(/JSN_SKIPPED_BASE:(\{[^\r\n]*\})/);
+  if (!match) throw errUsage('Base version inspection returned no verifiable result.');
+  try { return JSON.parse(match[1]); } catch { throw errUsage('Base version inspection returned invalid JSON.'); }
+}
+
+export async function revertSkippedUpdate(sdk, id, modCount) {
+  validateId(id);
+  if (!/^\d+$/.test(modCount || '')) throw errUsage('Finding update count is required for safe revert.');
+  const output = await sdk.executeScript(`(function() {
+    if (!gs.hasRole('admin')) throw new Error('Admin role required');
+    var record = new GlideRecordSecure('sys_upgrade_history_log');
+    if (!record.get('${id}') || !record.canWrite()) throw new Error('Finding unavailable or not writable');
+    if (record.getValue('disposition') !== '4' ||
+        ['', 'not_reviewed'].indexOf(record.getValue('resolution_status') || '') < 0 ||
+        record.getValue('sys_mod_count') !== '${modCount}') throw new Error('Finding changed or is not eligible');
+    new RevertUpdateVersionAjax().revertToBaseSystem('${id}');
+    gs.print('JSN_SKIPPED_REVERT:dispatched');
+  })();`, 'global');
+  if (!output.includes('JSN_SKIPPED_REVERT:dispatched')) throw errUsage('Revert dispatch outcome is unknown; inspect the finding before retrying.');
+  // The processor returns no success boolean. Caller must verify disposition and
+  // resolution by GET; dispatch alone must never be reported as success.
+}

package/src/skipped-updates.js

@@ -0,0 +1,177 @@
+import { createHash } from 'node:crypto';
+import { errUsage, errNotFound, AppError } from './errors.js';
+import { analyzeImpact, baselineFields, isImpactField } from './impact-analysis.js';
+
+export const SKIP_TABLE = 'sys_upgrade_history_log';
+const SKIPPED = ['4', '104', '9', '10', '11'];
+export const raw = value => String(value?.value ?? value ?? '');
+export const unresolved = record => Boolean(record && Object.hasOwn(record, 'disposition')
+  && Object.hasOwn(record, 'resolution_status') && SKIPPED.includes(raw(record.disposition))
+  && ['', 'not_reviewed'].includes(raw(record.resolution_status)));
+const FIELDS = 'sys_id,file_name,target_name,disposition,resolution_status,upgrade_history,reason,changed,sys_mod_count,sys_updated_on';
+const digest = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+const validId = id => /^[0-9a-fA-F]{32}$/.test(id || '');
+
+function validateSelection(ids, action) {
+  if (!Array.isArray(ids) || !ids.length || ids.length > 100 || ids.some(id => !validId(id))) {
+    throw errUsage('Select between 1 and 100 literal finding sys_ids.');
+  }
+  if (new Set(ids.map(id => id.toLowerCase())).size !== ids.length) throw errUsage('Duplicate finding sys_ids are not allowed.');
+  if (!['retain', 'revert'].includes(action)) throw errUsage('Select an explicit action: retain or revert. Recommendations are never actions.');
+}
+
+export async function reviewSkippedUpdate(sdk, id) {
+  if (!validId(id)) throw errUsage('A literal 32-hex finding sys_id is required.');
+  const finding = await sdk.get(SKIP_TABLE, id);
+  if (!finding) throw errNotFound('Skipped finding', id);
+  if (raw(finding.sys_id).toLowerCase() !== id.toLowerCase()) throw errUsage('Provider finding identity does not match selection.');
+  const fileName = raw(finding.file_name);
+  const match = fileName.match(/^([a-z][a-z0-9_]*)_([0-9a-fA-F]{32})$/);
+  const artifact = { update_name: fileName, name: raw(finding.target_name),
+    table: match?.[1] || null, sys_id: match?.[2] || null };
+  let current = null;
+  let baseline = null;
+  const unknown = [];
+  if (match) {
+    try { current = await sdk.get(artifact.table, artifact.sys_id); }
+    catch { unknown.push('Current artifact could not be read; access or availability is unknown.'); }
+  } else unknown.push('Artifact identity cannot be decoded from the provider update name.');
+  try { baseline = await sdk.getSkippedUpdateBaseline(id); }
+  catch { unknown.push('Base inspection is unavailable. Background-script access and version API availability are required.'); }
+  const dependencies = [];
+  if (match) {
+    try {
+      const refs = await sdk.list('sys_dictionary', new URLSearchParams({
+        sysparm_query: `reference=${artifact.table}^elementISNOTEMPTY^ORDERBYname^ORDERBYelement`,
+        sysparm_fields: 'name,element', sysparm_limit: '21', sysparm_display_value: 'false',
+      }));
+      if (refs.length > 20) unknown.push('Incoming reference discovery is truncated to 20 dictionary fields.');
+      for (const ref of refs.slice(0, 20)) {
+        const table = raw(ref.name), field = raw(ref.element);
+        if (!/^[a-z][a-z0-9_]*$/.test(table) || !/^[a-z][a-z0-9_]*$/.test(field)) continue;
+        try {
+          const rows = await sdk.list(table, new URLSearchParams({ sysparm_query: `${field}=${artifact.sys_id}^ORDERBYsys_id`,
+            sysparm_fields: 'sys_id', sysparm_limit: '11', sysparm_display_value: 'false' }));
+          for (const row of rows.slice(0, 10)) dependencies.push({ table, field, sys_id: raw(row.sys_id), relation: 'incoming_reference' });
+          if (rows.length > 10) unknown.push(`Incoming references from ${table}.${field} are truncated to 10 records.`);
+        } catch { unknown.push(`Incoming references from ${table}.${field} could not be read.`); }
+      }
+    } catch { unknown.push('Dictionary-backed incoming dependency discovery is unavailable.'); }
+  }
+  const impact = analyzeImpact({ artifact, current, baseline, dependencies, unknown });
+  const fields = baselineFields(baseline?.payload, artifact);
+  const fingerprint = digest({ finding, current, baseline });
+  return { sys_id: raw(finding.sys_id), artifact, finding: Object.fromEntries(FIELDS.split(',').map(key => [key, raw(finding[key])])),
+    impact, fingerprint, eligible: unresolved(finding),
+    // The provider's revert writes a NEW base version record whose payload is a
+    // copy of the version that was read here, so revert readback compares base
+    // CONTENT (this digest) instead of the previewed version sys_id.
+    baseline_payload_digest: typeof baseline?.payload === 'string' && baseline.payload
+      ? digest(baseline.payload) : null,
+    revert_supported: raw(finding.disposition) === '4' && validId(baseline?.sys_id)
+      && Boolean(current && raw(current.sys_id) === artifact.sys_id && fields
+        && Object.keys(fields).every(field => !isImpactField(field) || Object.hasOwn(current, field))) };
+}
+
+export async function prepareSkippedBatch(sdk, { ids, action, instance = '' }) {
+  validateSelection(ids, action);
+  const selected = [];
+  for (const id of ids) {
+    const review = await reviewSkippedUpdate(sdk, id);
+    if (!review.eligible) throw errUsage(`Finding ${id} is no longer unresolved and skipped.`);
+    if (action === 'revert' && !review.revert_supported) throw errUsage(`Revert is unsupported for ${id}: requires disposition 4, readable artifact and exact base version.`);
+    selected.push({ ...review, action, operation: action === 'retain'
+      ? 'Set resolution_status=reviewed_retained only; leave artifact unchanged.'
+      : 'Call RevertUpdateVersionAjax.revertToBaseSystem; replace customization with provider-selected base version.' });
+  }
+  if (action === 'revert') {
+    const includes = await sdk.list('sys_script_include', new URLSearchParams({
+      sysparm_query: 'name=RevertUpdateVersionAjax', sysparm_fields: 'script', sysparm_limit: '2', sysparm_display_value: 'false' }));
+    if (includes.length !== 1 || !/revertToBaseSystem\s*:\s*function\s*\(\s*sys_id\s*\)/.test(raw(includes[0].script))
+        || !raw(includes[0].script).includes('GlideappUpdateVersion.getVersion')) {
+      throw errUsage('Provider revert lifecycle contract is unavailable; no writes performed.');
+    }
+  }
+  const preview = { instance, selected, count: selected.length };
+  return { ...preview, confirmation_token: digest(preview), writes_performed: false };
+}
+
+
+export async function processSkippedBatch({ sdk, ids, action, instance = '', readOnly = false,
+  confirmationToken, confirm, onPreview }) {
+  if (readOnly) throw new AppError('read_only', 'Read-only profiles cannot process findings.');
+  const preview = await prepareSkippedBatch(sdk, { ids, action, instance });
+  // Preview precedes the sole confirmation. Never honor force or a profile's
+  // skip_confirmations here; this batch always requires explicit consent.
+  if (onPreview) await onPreview(preview);
+  if (confirmationToken) {
+    if (confirmationToken !== preview.confirmation_token) throw errUsage('Preview changed or confirmation token does not match. Review a new preview before confirming.');
+  } else if (confirm) {
+    if (!await confirm(preview)) return { preview, cancelled: true, results: [], success_count: 0, failure_count: 0, partial: false, writes_performed: false };
+  } else {
+    throw new AppError('confirmation_required', 'Review the exact batch preview before processing.',
+      `Run jsn skipped-updates preview --ids ${ids.join(',')} --action ${action}; review its exact selection, then process that selection with --confirm <preview-token>.`);
+  }
+  const results = [];
+  for (const selected of preview.selected) {
+    let attempted = false;
+    try {
+      const latest = await reviewSkippedUpdate(sdk, selected.sys_id);
+      if (!latest.eligible || latest.fingerprint !== selected.fingerprint) throw errUsage('Finding, artifact or base version changed after preview; no write attempted.');
+      attempted = true;
+      if (action === 'retain') await sdk.update(SKIP_TABLE, selected.sys_id, { resolution_status: 'reviewed_retained' });
+      else await sdk.revertSkippedUpdate(selected.sys_id, selected.finding.sys_mod_count);
+      const persisted = await sdk.get(SKIP_TABLE, selected.sys_id);
+      const expected = action === 'retain' ? 'reviewed_retained' : 'reviewed_reverted';
+      if (!persisted || raw(persisted.sys_id) !== selected.sys_id || raw(persisted.resolution_status) !== expected
+          || raw(persisted.disposition) !== (action === 'revert' ? '5' : selected.finding.disposition)) {
+        throw errUsage('Provider state readback did not verify the selected action.');
+      }
+      if (action === 'revert') {
+        const artifact = await sdk.get(selected.artifact.table, selected.artifact.sys_id);
+        const baseline = await sdk.getSkippedUpdateBaseline(selected.sys_id);
+        const fields = baselineFields(baseline?.payload, selected.artifact);
+        // RevertToBaseSystem reverts to the previewed base version and leaves a new
+        // base version record behind, so the sys_id legitimately changes. What must
+        // still match is the base CONTENT we previewed and the artifact now at base.
+        if (!artifact || raw(artifact.sys_id) !== selected.artifact.sys_id || !fields
+            || !validId(baseline?.sys_id) || typeof baseline?.payload !== 'string'
+            || digest(baseline.payload) !== selected.baseline_payload_digest
+            || Object.entries(fields).some(([field, value]) => isImpactField(field)
+              && (!Object.hasOwn(artifact, field) || raw(artifact[field]) !== value))) {
+          throw errUsage('Artifact readback did not verify the previewed base content on the reverted artifact.');
+        }
+        results.push({ sys_id: selected.sys_id, action, success: true, write_attempted: true,
+          resolution_status: raw(persisted.resolution_status), disposition: raw(persisted.disposition),
+          base_version: raw(baseline.sys_id), verified: true });
+        continue;
+      }
+      results.push({ sys_id: selected.sys_id, action, success: true, write_attempted: true,
+        resolution_status: raw(persisted.resolution_status), disposition: raw(persisted.disposition), verified: true });
+    } catch (err) {
+      results.push({ sys_id: selected.sys_id, action, success: false, write_attempted: attempted,
+        effect: attempted ? 'unknown' : 'unchanged', code: err.code || 'provider_error',
+        message: attempted ? 'Selected action or its readback failed; inspect this finding before retrying.' : err.message });
+    }
+  }
+  const successCount = results.filter(result => result.success).length;
+  return { preview, results, cancelled: false, success_count: successCount,
+    failure_count: results.length - successCount, partial: successCount > 0 && successCount < results.length,
+    writes_performed: results.some(result => result.write_attempted) };
+}
+
+export async function discoverSkippedUpdates(sdk, { limit = 100, offset = 0 } = {}) {
+  if (!Number.isInteger(limit) || limit < 1 || limit > 500 || !Number.isInteger(offset) || offset < 0) {
+    throw errUsage('Use a limit between 1 and 500 and a nonnegative integer offset.');
+  }
+  const params = new URLSearchParams({
+    sysparm_query: 'dispositionIN4,104,9,10,11^resolution_statusIN,not_reviewed^ORDERBYsys_id',
+    sysparm_fields: FIELDS, sysparm_display_value: 'all',
+    sysparm_limit: String(limit + 1), sysparm_offset: String(offset),
+  });
+  const rows = await sdk.list(SKIP_TABLE, params);
+  // Recheck locally: an instance can ignore a query field the caller cannot read.
+  if (rows.some(row => !unresolved(row))) throw errUsage('Provider returned a finding outside the unresolved skipped state.');
+  return { findings: rows.slice(0, limit), count: Math.min(rows.length, limit),
+    limit, offset, has_more: rows.length > limit, total: null };
+}