@jacebenson/jsn 4.3.7-dev.14 → 4.3.7-dev.16

package/README.md

@@ -81,6 +81,10 @@ jsn diff record --table incident --sys-id <sys_id> --profile-a dev --profile-b p
 jsn eval "gs.info('Hello World')"
 cat script.js | jsn eval --stdin          # pipe a script in (no shell escaping)
 
+# Now GraphQL (documents may contain mutations; read-only profiles are blocked)
+jsn graphql --query '{ GlideRecord_Query { incident(pagination: {limit: 2}) { _results { number { value } } } } }'
+cat incident.graphql | jsn graphql --stdin --variables '{"limit":2}'
+
 # Saved query snippets (stored locally, run against the active profile)
 jsn snippets save open-inc --table incident --query "active=true"
 jsn snippets run open-inc
@@ -117,6 +121,8 @@ Run `jsn` for the full grouped list. Commands are organized by ServiceNow domain
 
 **Data** — `records` (list/get/create/update/delete/count/bulk/attachments), `diff record` (cross-profile read-only comparison), `tables`, `columns`, `includes`, `import`, `logs` (list/show/follow), `snippets` (save/run), `users`, `groups`
 
+**Platform** — `platform health` (cluster records) and `platform stats` (bounded, read-only `/xmlstats.do` summary; allowlisted metrics only)
+
 Every command supports `--json`, `--query`, and `--help`.
 
 ## Instances
@@ -169,6 +175,10 @@ jsn incidents list
 
 For the credential identity, auth-method, diagnostics, migration, and concurrency contract, see [`docs/AUTH_LIFECYCLE.md`](docs/AUTH_LIFECYCLE.md).
 
+GraphQL uses ServiceNow's `/api/now/graphql` endpoint and sends `{query, variables}` through the authenticated SDK transport. The command preserves GraphQL `data` and `errors`; introspection and available namespaces depend on the target instance.
+
+`jsn platform stats` uses a fixed `GET /xmlstats.do` request. It never accepts a processor path, query parameters, or request body, and it does not emit raw XML, cookies, credentials, or full node identifiers. Oversized, HTML/login, permission, unsupported, timeout, and malformed responses are reported with bounded collector statuses; missing metrics remain unavailable rather than being reported as zero.
+
 ## Local data
 
 JSN stores durable local data under `~/.jsn/`. Documentation lives in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "4.3.7-dev.14",
+  "version": "4.3.7-dev.16",
   "description": "A command-line interface for ServiceNow that follows the Unix philosophy: simple, composable, and scriptable.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -70,6 +70,7 @@ import { atfCmd } from './commands/atf.js';
 import { approvalsCmd } from './commands/approvals.js';
 import { perfCmd } from './commands/perf.js';
 import { diffCmd } from './commands/diff.js';
+import { graphqlCmd } from './commands/graphql.js';
 
 function wrap(handler) {
   return async (argv) => {
@@ -373,6 +374,7 @@ export function buildCLI() {
     .command(approvalsCmd(wrap))
     .command(perfCmd(wrap))
     .command(diffCmd(wrap))
+    .command(graphqlCmd(wrap))
     .command(evalCmd(wrap))
     .command(restCmd(wrap))
     .command(skillCmd(wrap))

package/src/commands/graphql.js

@@ -0,0 +1,95 @@
+import fs from 'node:fs';
+import { declareCapabilities } from '../capabilities.js';
+
+// GraphQL documents may contain mutations. Gate the whole command so normal
+// instance/auth and read-only protections apply without attempting AST parsing.
+declareCapabilities('graphql', { mutationSubcommands: [''] });
+
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (chunk) => { data += chunk; });
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', reject);
+  });
+}
+
+export async function resolveGraphQLInput(argv) {
+  const sources = [
+    argv.document !== undefined,
+    argv.query !== undefined,
+    argv.queryFile !== undefined,
+    argv.stdin === true,
+  ].filter(Boolean).length;
+  if (sources !== 1) {
+    throw new Error('Provide exactly one GraphQL document via positional document, --query, --query-file, or --stdin');
+  }
+
+  let query;
+  if (argv.document !== undefined) query = argv.document;
+  else if (argv.query !== undefined) query = argv.query;
+  else if (argv.queryFile !== undefined) query = fs.readFileSync(argv.queryFile, 'utf-8');
+  else query = await readStdin();
+
+  query = String(query || '').trim();
+  if (!query) throw new Error('GraphQL document must not be empty');
+  return query;
+}
+
+export function parseGraphQLVariables(value) {
+  if (value === undefined) return {};
+  let variables;
+  try {
+    variables = JSON.parse(value);
+  } catch {
+    throw new Error('--variables must be valid JSON');
+  }
+  if (!variables || typeof variables !== 'object' || Array.isArray(variables)) {
+    throw new Error('--variables must be a JSON object');
+  }
+  return variables;
+}
+
+export function graphqlCmd(wrap) {
+  return {
+    command: 'graphql [document]',
+    describe: 'Execute a GraphQL document against ServiceNow Now GraphQL',
+    builder: (yargs) => yargs
+      .positional('document', {
+        describe: 'GraphQL document string',
+        type: 'string',
+      })
+      .option('query', {
+        type: 'string',
+        describe: 'GraphQL document string (alternative to positional)',
+      })
+      .option('query-file', {
+        type: 'string',
+        describe: 'Read the GraphQL document from a file',
+      })
+      .option('variables', {
+        type: 'string',
+        describe: 'GraphQL variables as a JSON object',
+      })
+      .option('stdin', {
+        type: 'boolean',
+        describe: 'Read the GraphQL document from stdin',
+      }),
+    handler: wrap(async (argv, app) => {
+      const query = await resolveGraphQLInput(argv);
+      const variables = parseGraphQLVariables(argv.variables);
+      const endpoint = `${app.getEffectiveInstance()}/api/now/graphql`;
+      const result = await app.sdk.request(endpoint, {
+        method: 'POST',
+        body: JSON.stringify({ query, variables }),
+      });
+      const errorCount = Array.isArray(result?.errors) ? result.errors.length : 0;
+      app.ok(result, {
+        summary: errorCount
+          ? `GraphQL returned ${errorCount} error(s)`
+          : 'GraphQL request succeeded',
+      });
+    }),
+  };
+}

package/src/commands/platform.js

@@ -1,3 +1,5 @@
+import { declareCapabilities } from '../capabilities.js';
+
 function numberOrString(value) {
   const n = Number(value);
   return value !== '' && Number.isFinite(n) ? n : value;
@@ -24,6 +26,179 @@ function statsForWindow(xml, parent, window) {
   return tagAttributes(parentMatch[1], window);
 }
 
+export const XMLSTATS_MAX_BYTES = 4 * 1024 * 1024;
+
+function metric(value) {
+  if (value === undefined || value === null || String(value).trim() === '') {
+    return { value: null, availability: 'unavailable' };
+  }
+  return { value: numberOrString(String(value).trim()), availability: 'available' };
+}
+
+function firstNestedText(xml, parent, child) {
+  const parentMatch = xml.match(new RegExp(`<${parent}\\b[^>]*>([\\s\\S]*?)</${parent}>`));
+  return parentMatch ? tagText(parentMatch[1], child) : undefined;
+}
+
+function allowlistedStats(xml) {
+  const unavailable = [];
+  const add = (path, value) => {
+    const result = metric(value);
+    if (result.availability === 'unavailable') unavailable.push(path);
+    return result;
+  };
+
+  const cluster = xml.match(/<cluster\.status\b[^>]*>([\s\S]*?)<\/cluster\.status>/);
+  const nodeXml = cluster?.[1]?.match(/<node\b[^>]*>([\s\S]*?)<\/node>/)?.[1] || '';
+  const daily = statsForWindow(xml, 'all_transactions', 'daily') || {};
+  const semaphores = [];
+  for (const match of xml.matchAll(/<semaphores([^>]*)\/>/g)) {
+    const attrs = {};
+    for (const [, key, value] of match[1].matchAll(/([\w.-]+)="([^"]*)"/g)) attrs[key] = value;
+    if (!attrs.name && !attrs.available && !attrs.borrowed && !attrs.maximum_concurrency && !attrs.queue_depth) continue;
+    semaphores.push({
+      name: attrs.name || 'unnamed',
+      available: add(`semaphores[${attrs.name || 'unnamed'}].available`, attrs.available),
+      borrowed: add(`semaphores[${attrs.name || 'unnamed'}].borrowed`, attrs.borrowed),
+      maximum: add(`semaphores[${attrs.name || 'unnamed'}].maximum`, attrs.maximum_concurrency),
+      queue_depth: add(`semaphores[${attrs.name || 'unnamed'}].queue_depth`, attrs.queue_depth),
+    });
+  }
+  if (semaphores.length === 0) unavailable.push('semaphores');
+
+  return {
+    node: {
+      status: add('node.status', tagText(nodeXml, 'status')),
+      type: add('node.type', firstNestedText(nodeXml, 'node_type', 'name')),
+    },
+    queue: {
+      length: add('queue.length', tagText(xml, 'queue.length')),
+      age: add('queue.age', tagText(xml, 'queue.age')),
+    },
+    active_sessions: add('active_sessions', tagText(xml, 'servlet.active.sessions')),
+    memory_pressure: add('memory_pressure', tagText(xml, 'memory_pressure')),
+    semaphores,
+    transactions: {
+      daily: {
+        count: add('transactions.daily.count', daily.count),
+        mean: add('transactions.daily.mean', daily.mean),
+        median: add('transactions.daily.median', daily.median),
+        ninetypercent: add('transactions.daily.ninetypercent', daily.ninetypercent),
+        max: add('transactions.daily.max', daily.max),
+      },
+    },
+    unavailable,
+  };
+}
+
+export function parsePlatformStatsXml(xml) {
+  const source = String(xml || '');
+  if (Buffer.byteLength(source) > XMLSTATS_MAX_BYTES) throw new Error('xmlstats response exceeds the bounded size limit');
+  if (!/^\s*(?:<\?xml[\s\S]*?\?>\s*)?<xmlstats\b[^>]*>/i.test(source)
+    || !/<\/xmlstats>\s*$/i.test(source)) {
+    throw new Error('Malformed XML: expected an xmlstats document');
+  }
+  const stack = [];
+  for (const match of source.matchAll(/<\/?([A-Za-z][\w.:-]*)(?:\s[^>]*)?>/g)) {
+    const token = match[0];
+    const name = match[1];
+    if (/^<\//.test(token)) {
+      if (stack.pop() !== name) throw new Error('Malformed XML: mismatched tags');
+    } else if (!/\/\s*>$/.test(token)) {
+      stack.push(name);
+    }
+  }
+  if (stack.length !== 0) throw new Error('Malformed XML: unclosed tags');
+  return allowlistedStats(source);
+}
+
+async function readBoundedResponse(response, maxBytes = XMLSTATS_MAX_BYTES) {
+  if (!response.body?.getReader) {
+    const text = await response.text();
+    return Buffer.byteLength(text) > maxBytes ? { tooLarge: true, bytes: Buffer.byteLength(text) } : { text, bytes: Buffer.byteLength(text) };
+  }
+  const reader = response.body.getReader();
+  const chunks = [];
+  let bytes = 0;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    bytes += value.byteLength;
+    if (bytes > maxBytes) {
+      await reader.cancel();
+      return { tooLarge: true, bytes };
+    }
+    chunks.push(value);
+  }
+  const body = new Uint8Array(bytes);
+  let offset = 0;
+  for (const chunk of chunks) {
+    body.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return { text: new TextDecoder().decode(body), bytes };
+}
+
+function looksLikeLoginHtml(response, body) {
+  const contentType = response.headers?.get?.('content-type') || '';
+  return /text\/html/i.test(contentType) || /^\s*<(?:!doctype\s+html|html\b)/i.test(body);
+}
+
+export async function collectPlatformStats(sdk, instance) {
+  let response;
+  try {
+    response = await sdk.fetchResponse(`${instance}/xmlstats.do`, {
+      method: 'GET',
+      headers: { Accept: 'application/xml,text/xml' },
+    });
+  } catch (error) {
+    const message = String(error?.message || '').toLowerCase();
+    return { status: /timeout|timed out/.test(message) ? 'timeout' : 'unavailable', reason: /timeout|timed out/.test(message) ? 'request timed out' : 'request failed' };
+  }
+
+  if (response.status === 401 || response.status === 403) return { status: 'permission_denied', reason: `HTTP ${response.status}` };
+  if (response.status === 404 || response.status === 405) return { status: 'unsupported', reason: `HTTP ${response.status}` };
+  if (!response.ok) return { status: 'unavailable', reason: `HTTP ${response.status}` };
+
+  const body = await readBoundedResponse(response);
+  if (body.tooLarge) return { status: 'too_large', reason: `response exceeded ${XMLSTATS_MAX_BYTES} bytes`, bytes: body.bytes };
+  if (looksLikeLoginHtml(response, body.text)) return { status: 'login_redirect', reason: 'received HTML instead of xmlstats XML', bytes: body.bytes };
+
+  try {
+    const metrics = parsePlatformStatsXml(body.text);
+    const status = metrics.unavailable.length > 0 ? 'partial' : 'success';
+    return {
+      status,
+      reason: status === 'partial' ? 'some allowlisted metrics were unavailable' : null,
+      bytes: body.bytes,
+      metrics,
+    };
+  } catch {
+    return { status: 'malformed_xml', reason: 'response was not a valid xmlstats document', bytes: body.bytes };
+  }
+}
+
+function metricText(item) {
+  return item?.availability === 'available' ? String(item.value) : 'unavailable';
+}
+
+export function formatPlatformStats(result) {
+  const lines = [`STATUS: ${result.status}`];
+  if (result.reason) lines.push(`REASON: ${result.reason}`);
+  const m = result.metrics;
+  if (!m) return `${lines.join('\\n')}\\n`;
+  lines.push(`NODE: ${metricText(m.node.status)} / ${metricText(m.node.type)}`);
+  lines.push(`QUEUE: ${metricText(m.queue.length)} length, ${metricText(m.queue.age)} age`);
+  lines.push(`SESSIONS: ${metricText(m.active_sessions)}`);
+  lines.push(`MEMORY PRESSURE: ${metricText(m.memory_pressure)}`);
+  lines.push(`TRANSACTIONS DAILY: ${metricText(m.transactions.daily.count)} count, ${metricText(m.transactions.daily.mean)} mean, ${metricText(m.transactions.daily.ninetypercent)} p90, ${metricText(m.transactions.daily.max)} max`);
+  if (m.semaphores.length === 0) lines.push('SEMAPHORES: unavailable');
+  else for (const semaphore of m.semaphores) {
+    lines.push(`SEMAPHORE ${semaphore.name}: ${metricText(semaphore.available)} available, ${metricText(semaphore.borrowed)} borrowed, ${metricText(semaphore.maximum)} maximum, ${metricText(semaphore.queue_depth)} queue`);
+  }
+  return `${lines.join('\\n')}\\n`;
+}
+
 export function parseNodeStatsXml(xml) {
   const source = String(xml || '');
   const result = {};
@@ -91,6 +266,7 @@ function formatHealth(nodes) {
 }
 
 export function platformCmd(wrap) {
+  declareCapabilities('platform', { mutationSubcommands: [] });
   return {
     command: 'platform',
     describe: 'Inspect read-only platform health and node statistics',
@@ -122,6 +298,15 @@ export function platformCmd(wrap) {
         }
         app.ok({ table: 'sys_cluster_state', node_count: nodes.length, nodes, _formatted: formatHealth(nodes), security: { raw_xml: 'excluded', sensitive_fields: 'excluded' }, context: { instance_url: app.getEffectiveInstance() } }, { summary: `Platform health: ${nodes.length} node(s)` });
       }),
+    }).command({
+      command: 'stats',
+      describe: 'Show bounded, read-only platform statistics from xmlstats.do',
+      handler: wrap(async (argv, app) => {
+        app.requireInstance();
+        const result = await collectPlatformStats(app.sdk, app.getEffectiveInstance());
+        result._formatted = formatPlatformStats(result);
+        app.ok(result, { summary: `Platform stats: ${result.status}` });
+      }),
     }),
   };
 }