@jacebenson/jsn 4.2.1 → 4.2.3

package/README.md

@@ -53,6 +53,12 @@ jsn incidents create --description "Server down" --priority 1
 # Admin tasks
 jsn flows list                                # Interactive picker with pagination
 jsn flows show "Assign Task"                  # Full flow detail
+jsn flows executions                          # All states, newest first
+jsn flows executions --active                  # Only waiting/running/queued
+jsn flows executions --since "2026-08-25 00:00:00" --until "2026-08-26 00:00:00"
+jsn flows executions --summary                 # Server totals + sampled duration metrics by flow
+jsn flows executions --limit 100               # Inspect more rows from the matching population
+jsn flows executions --record <sys_id>        # Executions for one source record
 jsn rules list --query "collection=incident"
 jsn updatesets set "My Feature"
 
@@ -78,6 +84,20 @@ jsn snippets run open-inc
 jsn logs follow --level error --tail 10
 ```
 
+### Flow execution fields
+
+`jsn flows executions` reads `sys_flow_context` and returns both the raw row and a normalized `execution` object. JSN discovers the runtime columns from `sys_dictionary` first, then uses these mappings:
+
+- `started`: `started`, `start_time`, `started_at`, then `sys_created_on`
+- `ended`: `ended`, `end_time`, `ended_at`, then `completed_on`
+- `duration_seconds`: stored `duration`, `run_time`, or `execution_duration`, otherwise `ended - started`
+- `waiting_age_seconds`: current time minus `started` while the status is waiting, queued, paused, or pending
+- `execution_age_seconds`: current time minus `started` while the status is running, executing, or processing
+- `status`: `state`, then `status`, then `execution_state`
+- `error`: `error`, `error_message`, `exception`, then `message`
+
+The timestamp fields are instance-dependent. `sys_created_on` is a fallback for when the context row was created, not a claim that it is the true runtime start time.
+
 ## Commands
 
 Run `jsn` for the full grouped list. Commands are organized by ServiceNow domain:

package/package.json

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

package/src/app.js

@@ -131,10 +131,10 @@ export class App {
     process.stderr.write('# Use `jsn scopes` to change scope, `jsn updatesets set` to change updateset\n');
     process.stderr.write('PROFILE   USER      [SCOPE]           UPDATE SET\n');
 
-    const profileStr = hyperlink(`${String(this.context.profileName).padEnd(9)}${roBadge}`, instanceLink);
+    const profileStr = `${hyperlink(String(this.context.profileName).padEnd(9), instanceLink)}${roBadge}`;
     const userStr = hyperlink(String(displayUserName).padEnd(9), userLink);
     const scopeStr = hyperlink(String(scopeFormatted).padEnd(17), scopeLink);
-    const updateSetStr = hyperlink(updateSet, updateSetLink);
+    const updateSetStr = hyperlink(String(updateSet), updateSetLink);
 
     process.stderr.write(`${profileStr} ${userStr} ${scopeStr} ${updateSetStr}\n\n`);
 

package/src/auth.js

@@ -366,6 +366,9 @@ export class AuthManager {
     if (getBasicAuthFromEnv(instance)) return true;
     const creds = loadCredentials(instance, this._activeUsername());
     if (!creds) return false;
+    if (creds.auth_method === 'basic') {
+      return Boolean(creds.username && creds.password);
+    }
     if (creds.expires_at && Date.now() >= creds.expires_at * 1000) return false;
     return !!creds.access_token;
   }
@@ -384,11 +387,11 @@ export class AuthManager {
     return this.getCredentialsFor(instance);
   }
 
-  getCredentialsFor(instance) {
+  getCredentialsFor(instance, username = this._activeUsername()) {
     // Check basic auth from env vars first
     const basicCreds = getBasicAuthFromEnv(instance);
     if (basicCreds) return basicCreds;
-    const creds = loadCredentials(instance, this._activeUsername());
+    const creds = loadCredentials(instance, username);
     if (!creds) {
       throw errAuth(`Not authenticated for ${instance}`);
     }
@@ -483,17 +486,19 @@ export class AuthManager {
    * Reads SN_USERNAME/SN_PASSWORD (or SN_<INSTANCE>_USERNAME/SN_<INSTANCE>_PASSWORD).
    * Stores the basic auth credentials so they persist across sessions.
    */
-  async loginWithPassword(instanceURL) {
+  async loginWithPassword(instanceURL, username = this._activeUsername()) {
     instanceURL = normalizeInstanceURL(instanceURL);
-    const creds = getBasicAuthFromEnv(instanceURL);
-    if (!creds) {
+    const envCreds = getBasicAuthFromEnv(instanceURL);
+    const storedCreds = loadCredentials(instanceURL, username);
+    const creds = envCreds || storedCreds;
+    if (!creds || creds.auth_method !== 'basic' || !creds.username || !creds.password) {
       throw errAuth(
-        `No basic auth credentials found in environment.\n\n` +
+        `No basic auth credentials found in environment or stored profile.\n\n` +
         `Set the following environment variables:\n` +
         `  SN_USERNAME=admin           (or SN_${envVarName(instanceURL)}_USERNAME)\n` +
         `  SN_PASSWORD=<password>      (or SN_${envVarName(instanceURL)}_PASSWORD)\n\n` +
         `Then run:\n` +
-        `  jsn auth login --password ${instanceURL}`
+        `  jsn auth login --basic ${instanceURL}`
       );
     }
     saveCredentials(instanceURL, creds, creds.username);

package/src/cli.js

@@ -29,6 +29,9 @@ import { groupsCmd } from './commands/groups.js';
 import { groupMembersCmd } from './commands/groupmembers.js';
 import { groupRolesCmd } from './commands/grouproles.js';
 import { ticketsCmd } from './commands/tickets.js';
+import { transactionsCmd } from './commands/transactions.js';
+import { instanceCmd } from './commands/instance.js';
+import { platformCmd } from './commands/platform.js';
 import { codesearchCmd } from './commands/codesearch.js';
 import { versionCmd } from './commands/version.js';
 import { devCmd } from './commands/dev.js';
@@ -354,6 +357,9 @@ export function buildCLI() {
     // DATA
     .command(cmdbCmd(wrap))
     .command(recordsCmd(wrap))
+    .command(transactionsCmd(wrap))
+    .command(instanceCmd(wrap))
+    .command(platformCmd(wrap))
     .command(snippetsCmd(wrap))
     .command(ticketsCmd(wrap))
     .command(codesearchCmd(wrap))

package/src/commands/auth.js

@@ -82,6 +82,18 @@ export function resolveInstanceArg(arg, cfg) {
   return normalizeInstanceURL(`${trimmed}.service-now.com`);
 }
 
+/**
+ * Select the login method. Explicit Basic Auth wins; otherwise reuse the
+ * method recorded on an existing profile. New instances remain OAuth by
+ * default.
+ */
+export function shouldUseBasicAuth(argv = {}, cfg = {}, instanceURL = '') {
+  if (argv.basic || argv.password) return true;
+  return Object.values(cfg.profiles || {}).some(profile =>
+    profile.instance_url === instanceURL && profile.auth_method === 'basic'
+  );
+}
+
 /**
  * Pick a profile by name — interactive search picker when ambiguous,
  * auto-selects when there's exactly one, throws when none configured.
@@ -111,9 +123,10 @@ export async function pickProfile(app, message) {
  * always asks otherwise.
  */
 export function resolveWizardInstance(app, argv = {}) {
-  // app.getEffectiveInstance() is the session-backed read (production App);
-  // the _overrideInstance fallback keeps hand-rolled test fakes honest.
-  return process.env.SERVICENOW_INSTANCE_URL || app.getEffectiveInstance?.() || app._overrideInstance || argv.instance || '';
+  // Only explicit inputs may pre-fill the wizard. The active/default profile
+  // belongs to the existing connection and must not silently become the new
+  // instance when setup is adding a profile.
+  return process.env.SERVICENOW_INSTANCE_URL || app._overrideInstance || argv.instance || '';
 }
 
 /**
@@ -426,7 +439,7 @@ export async function removeProfile(app, name) {
 export function authCmd(wrap) {
   return {
     command: 'auth [subcommand]',
-    describe: 'Manage authentication (OAuth or basic auth via env vars)',
+    describe: 'Manage authentication (OAuth or Basic Auth)',
     builder: (yargs) => {
       return yargs
         .command({
@@ -437,8 +450,9 @@ export function authCmd(wrap) {
               describe: 'Authorization code from browser (bypasses interactive prompt)',
               type: 'string',
             })
-            .option('password', {
-              describe: 'Authenticate with basic auth via env vars (SN_USERNAME/SN_PASSWORD)',
+            .option('basic', {
+              alias: 'password',
+              describe: 'Authenticate with Basic Auth via env vars (SN_USERNAME/SN_PASSWORD)',
               type: 'boolean',
             })
             .option('print-url', {
@@ -497,15 +511,20 @@ export function authCmd(wrap) {
 Examples:
   jsn auth login https://dev12345.service-now.com
   jsn auth login dev373698
-  jsn auth login --password https://dev328604.service-now.com
+  jsn auth login --basic https://dev328604.service-now.com
 
 Find your instance URL in your browser's address bar when logged into ServiceNow.`);
               }
             }
 
-            // --password: authenticate with basic auth from env vars
-            if (argv.password) {
-              await app.auth.loginWithPassword(instanceURL);
+            const targetProfile = Object.values(app.config.profiles || {})
+              .find(profile => profile.instance_url === instanceURL);
+            const targetUsername = targetProfile?.username || '';
+            const useBasic = shouldUseBasicAuth(argv, app.config, instanceURL);
+            // --basic (with --password as a compatibility alias): authenticate
+            // with basic auth from env vars and persist it for this profile.
+            if (useBasic) {
+              await app.auth.loginWithPassword(instanceURL, targetUsername || undefined);
             }
             // --print-url with --wait-file: print URL and wait for code file
             else if (argv.printUrl && argv.waitFile) {
@@ -528,9 +547,12 @@ Find your instance URL in your browser's address bar when logged into ServiceNow
             // Verify auth by fetching current user
             let username = '';
             try {
-              if (!app.sdk) {
+              if (!app.sdk || targetUsername) {
                 const { SDKClient } = await import('../sdk.js');
-                app.sdk = new SDKClient(instanceURL, app.auth);
+                const authProvider = targetUsername
+                  ? { getCredentials: () => app.auth.getCredentialsFor(instanceURL, targetUsername) }
+                  : app.auth;
+                app.sdk = new SDKClient(instanceURL, authProvider);
               }
               const user = await app.sdk.getCurrentUser();
               username = user?.user_name || user?.name || '';
@@ -560,7 +582,7 @@ Find your instance URL in your browser's address bar when logged into ServiceNow
             app.config.profiles[profileName] = {
               ...(app.config.profiles[profileName] || {}),
               instance_url: instanceURL,
-              auth_method: argv.password ? 'basic' : 'oauth',
+              auth_method: useBasic ? 'basic' : 'oauth',
               username: username || undefined,
               read_only: argv['read-only'] || undefined,
               skip_confirmations: argv['skip-confirmations'] || undefined,
@@ -571,7 +593,7 @@ Find your instance URL in your browser's address bar when logged into ServiceNow
             // so they're keyed by <user>@<instance> for per-user isolation.
             // The legacy bare-instance key is cleaned up behind the
             // AuthManager seam (credential-store internals don't leak here).
-            if (!argv.password && username) {
+            if (!useBasic && username) {
               app.auth.migrateLegacyCredential(instanceURL, username);
             }
 

package/src/commands/dev/flows.js

@@ -1,4 +1,5 @@
 import { formatRecordForDisplay, getStringField, interactiveList } from '../../helpers.js';
+import { discoverFlowContextFields, normalizeFlowContext, summarizeFlowContexts, formatFlowContextSummary, aggregateFlowContextMappings, mergeFlowContextStats, buildFlowContextQuery } from '../../flow-context.js';
 import { declareCapabilities } from '../../capabilities.js';
 
 declareCapabilities('flows', { mutationSubcommands: ['create', 'update', 'delete'], devAlias: true });
@@ -66,6 +67,62 @@ export function flowsCmd(wrap) {
             }, { summary: `${records.length} flow(s)` });
           }),
         })
+        .command({
+          command: 'executions',
+          aliases: ['runs', 'contexts'],
+          describe: 'Show Flow Designer executions from sys_flow_context',
+          builder: (y) => y
+            .option('query', { type: 'string', describe: 'Encoded query (e.g. "state=WAITING" or "source_record=<sys_id>")' })
+            .option('record', { type: 'string', describe: 'Only executions for this source record sys_id' })
+            .option('since', { type: 'string', describe: 'Only contexts created on or after this timestamp' })
+            .option('until', { type: 'string', describe: 'Only contexts created on or before this timestamp' })
+            .option('limit', { alias: 'l', type: 'number', default: 50, describe: 'Max executions' })
+            .option('summary', { type: 'boolean', default: false, describe: 'Return local counts and duration metrics by flow' })
+            .option('active', { type: 'boolean', default: false, describe: 'Only waiting, running, and queued executions' })
+            .option('all', { type: 'boolean', default: false, describe: 'Compatibility flag; all states are now shown by default' }),
+          handler: wrap(async (argv, app) => {
+            app.requireInstance();
+            const fields = await discoverFlowContextFields(app.sdk);
+            const query = buildFlowContextQuery({
+              record: argv.record,
+              since: argv.since,
+              until: argv.until,
+              query: argv.query || (argv.active ? 'stateINWAITING,RUNNING,QUEUED' : ''),
+            });
+            const params = new URLSearchParams();
+            params.set('sysparm_query', query);
+            params.set('sysparm_limit', String(argv.limit));
+            params.set('sysparm_fields', [...fields].join(','));
+            params.set('sysparm_display_value', 'all');
+            const records = await app.sdk.list('sys_flow_context', params);
+            const executions = records.map(record => normalizeFlowContext(record));
+            const sampledSummary = summarizeFlowContexts(executions);
+            let executionSummary = sampledSummary;
+            if (argv.summary) {
+              const [totalCount, stats] = await Promise.all([
+                app.sdk.aggregateCount('sys_flow_context', query).catch(() => null),
+                app.sdk.aggregate('sys_flow_context', { query, groupBy: ['name', 'state'], count: true }).catch(() => null),
+              ]);
+              executionSummary = mergeFlowContextStats(stats?.groups || stats?.stats || [], sampledSummary, totalCount);
+            }
+            const data = {
+              table: 'sys_flow_context',
+              count: argv.summary ? executionSummary.total_count ?? executions.length : executions.length,
+              sample_count: executions.length,
+              query,
+              fields: [...fields],
+              field_mapping: aggregateFlowContextMappings(executions),
+              missing_fields: [...new Set(executions.flatMap(execution => execution.missing_fields))],
+              summary: executionSummary,
+              executions: argv.summary ? undefined : executions,
+              _formatted: argv.summary ? formatFlowContextSummary(executionSummary) : undefined,
+              context: { instance_url: app.getEffectiveInstance(), timezone: 'UTC' },
+            };
+            app.ok(data, { summary: argv.summary
+              ? `${executionSummary.total_count ?? executions.length} matching flow execution(s), ${executions.length} sampled`
+              : `${executions.length} flow execution(s)` });
+          }),
+        })
         .command({
           command: 'show <identifier>',
           aliases: ['get'],
@@ -128,6 +185,7 @@ export function flowsCmd(wrap) {
       console.log('');
       console.log('Available subcommands:');
       console.log('  list                  List flows');
+      console.log('  executions            Show flow executions from sys_flow_context');
       console.log('  show <identifier>     Show flow details by name or sys_id');
       console.log('  create                Create a new flow (not yet implemented)');
       console.log('  update <identifier>   Update a flow (not yet implemented)');
@@ -650,10 +708,66 @@ async function formatStepLine(stepNum, pad, step, ctx) {
     case 'subflow':
       return formatSubFlowStep(stepNum, pad, step.data, ctx);
     default:
-      return formatActionStep(stepNum, pad, step.data, ctx);
+      return formatActionStepWithChildren(stepNum, pad, step.data, ctx);
+  }
+}
+
+async function formatActionStepWithChildren(stepNum, pad, action, ctx) {
+  const lines = formatActionStep(stepNum, pad, action, ctx);
+  const depth = ctx?.depth ?? 1;
+  if (!ctx?.sdk?.inspectCustomAction || depth <= 1) return lines;
+
+  const actionName = getActionName(action);
+  if (!actionName) return lines;
+
+  if (!ctx.customActionCache) ctx.customActionCache = new Map();
+  if (!ctx.customActionCache.has(actionName)) {
+    ctx.customActionCache.set(actionName, ctx.sdk.inspectCustomAction(actionName).catch(() => null));
+  }
+  const details = await ctx.customActionCache.get(actionName);
+  const steps = details?.steps;
+  if (!Array.isArray(steps) || steps.length === 0 || !hasUsefulActionSteps(actionName, steps)) return lines;
+
+  lines.push(`${pad}   ↳ Internal action steps`);
+  const ordered = [...steps].sort((a, b) => parseOrderField(a) - parseOrderField(b));
+  ordered.forEach((step, index) => {
+    const label = firstNonEmpty(getStringField(step, 'label'), getStringField(step, 'name'), 'Action step');
+    const type = getNestedString(step, 'step_type', 'display_value') || getStringField(step, 'step_type');
+    const suffix = type ? ` - ${type}` : '';
+    lines.push(`${pad}      Step ${index + 1}: ${label}${suffix}`);
+    appendStepValues(lines, pad + '         ', step, ctx);
+  });
+  return lines;
+}
+
+function hasUsefulActionSteps(actionName, steps) {
+  if (steps.length !== 1) return true;
+  const step = steps[0];
+  const label = firstNonEmpty(getStringField(step, 'label'), getStringField(step, 'name'))
+    .replace(/\s+step$/i, '').trim().toLowerCase();
+  return label !== actionName.trim().toLowerCase();
+}
+
+function appendStepValues(lines, pad, step, ctx) {
+  for (const field of ['inputs', 'outputs', 'extended_inputs', 'extended_outputs']) {
+    const value = getStringField(step, field);
+    if (!value) continue;
+    const resolved = resolveGuidPills(value, ctx?.labelCache);
+    for (const part of resolved.split('^')) {
+      if (part) lines.push(`${pad}${field}: ${part}`);
+    }
   }
 }
 
+function getActionName(action) {
+  return firstNonEmpty(
+    getNestedString(action, 'actionType', 'fName'),
+    getStringField(action, 'actionName'),
+    getStringField(action, 'actionInternalName'),
+    getStringField(action, 'name'),
+  );
+}
+
 export function formatActionStep(stepNum, pad, action, ctx) {
   const lines = [];
   let actionName = firstNonEmpty(
@@ -700,7 +814,6 @@ export function formatActionStep(stepNum, pad, action, ctx) {
       if (inputName === 'table_name' && showsTableSuffix) continue;
 
       let inputValue = firstNonEmpty(getStringField(raw, 'displayValue'), getStringField(raw, 'value'));
-      if (!inputValue) continue;
 
       // Catalog variable selections arrive as "sys_id:table" pairs; resolve
       // them to readable names when we have a resolver map (built per flow).
@@ -716,6 +829,11 @@ export function formatActionStep(stepNum, pad, action, ctx) {
         label = firstNonEmpty(getStringField(raw.parameter, 'label'), label);
       }
 
+      if (!inputValue) {
+        lines.push(`${pad}    ${label}: (not set)`);
+        continue;
+      }
+
       // ServiceNow writes multi-field payloads (encoded-query style) as
       // "field=value^field2=value2". Split those onto one line per field;
       // plain long strings stay on a single line, untruncated.

package/src/commands/dev/rest.js

@@ -26,6 +26,11 @@ export function restCmd(wrap) {
           type: 'string',
           describe: 'Table name shorthand for api/now/table/{table}',
         })
+        .option('raw', {
+          type: 'boolean',
+          default: false,
+          describe: 'Return non-JSON response bodies as text (for XML/HTML diagnostic endpoints)',
+        })
         .option('query', {
           type: 'string',
           describe: 'Query parameters string',
@@ -63,7 +68,9 @@ export function restCmd(wrap) {
         requestOptions.body = argv.data;
       }
 
-      const result = await app.sdk.request(url, requestOptions);
+      const result = argv.raw
+        ? await app.sdk.rawRequest(url, requestOptions)
+        : await app.sdk.request(url, requestOptions);
       app.ok(result, { summary: `${method} ${endpoint}` });
     }),
   };