@jacebenson/jsn 3.4.0 → 3.4.2

package/package.json

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

package/src/cli.js

@@ -225,7 +225,11 @@ export function buildCLI() {
         }
 
         if (shouldCheckSkill) {
-          checkSkill().catch(() => {});
+          try {
+            checkSkill();
+          } catch {
+            // Non-fatal — don't crash the CLI if skill check fails
+          }
 
           try {
             fs.mkdirSync(globalConfigDir(), { recursive: true });

package/src/commands/dev/flows.js

@@ -14,7 +14,12 @@ export function flowsCmd(wrap) {
           builder: (y) => y
             .option('query', { type: 'string', describe: 'Encoded query (e.g. "nameLIKEincident" or "active=true")' })
             .option('columns', { alias: ['c', 'fields'], type: 'string', describe: 'Comma-separated columns (e.g. "number,short_description")' })
-            .option('limit', { alias: 'l', type: 'number', default: 50, describe: 'Max records' }),
+            .option('limit', { alias: 'l', type: 'number', default: 50, describe: 'Max records' })
+            .option('depth', {
+              type: 'number',
+              default: 2,
+              describe: 'Expand nested subflows to this depth (1 = subflow names only, 2 = one level, 3+ = deeper)',
+            }),
           handler: wrap(async (argv, app) => {
             app.requireInstance();
             const columns = argv.columns ? argv.columns.split(',') : ['name', 'active', 'description', 'sys_created_by', 'sys_updated_on'];
@@ -28,7 +33,13 @@ export function flowsCmd(wrap) {
             if (picked === undefined) return; // user cancelled
             if (picked) {
               const inspection = await app.sdk.inspectFlow(getStringField(picked, 'sys_id'));
-              const formatted = formatFlowInspection(inspection, app.getEffectiveInstance());
+              const ctx = {
+                sdk: app.sdk,
+                instanceURL: app.getEffectiveInstance(),
+                depth: Math.max(1, Math.floor(argv.depth ?? 2)),
+                visited: new Set([inspection.flow.sysID]),
+              };
+              const formatted = await formatFlowInspection(inspection, ctx);
               return app.ok({ ...inspection, _formatted: formatted }, {
                 summary: `Flow: ${inspection.flow.name}`,
                 breadcrumbs: [{ action: 'list', cmd: 'jsn flows list', description: 'Back to all flows' }],
@@ -56,9 +67,21 @@ export function flowsCmd(wrap) {
           command: 'show <identifier>',
           aliases: ['get'],
           describe: 'Show flow details by name or sys_id',
+          builder: (y) => y
+            .option('depth', {
+              type: 'number',
+              default: 2,
+              describe: 'Expand nested subflows to this depth (1 = subflow names only, 2 = one level, 3+ = deeper)',
+            }),
           handler: wrap(async (argv, app) => {
             const inspection = await app.sdk.inspectFlow(argv.identifier);
-            const formatted = formatFlowInspection(inspection, app.getEffectiveInstance());
+            const ctx = {
+              sdk: app.sdk,
+              instanceURL: app.getEffectiveInstance(),
+              depth: Math.max(1, Math.floor(argv.depth ?? 2)),
+              visited: new Set([inspection.flow.sysID]),
+            };
+            const formatted = await formatFlowInspection(inspection, ctx);
             const data = { ...inspection, _formatted: formatted };
             app.ok(data, {
               summary: `Flow: ${inspection.flow.name}`,
@@ -109,15 +132,16 @@ export function flowsCmd(wrap) {
       console.log('');
       console.log('Run "jsn flows <command> --help" for details.');
       console.log('');
-      console.log('Note: Flow inspection detail varies. V2 flows (with payload)');
-      console.log('show full action inputs and conditions. Subflows and V1 flows');
-      console.log('show step names only.');
+      console.log('Note: Flow structure comes from the ProcessFlow API (the Flow');
+      console.log('Designer UI source), so V1, V2, and subflow definitions all');
+      console.log('render with full action inputs and conditions.');
     },
   };
 }
 
-function formatFlowInspection(inspection, instanceURL) {
+async function formatFlowInspection(inspection, ctx) {
   const lines = [];
+  const instanceURL = ctx?.instanceURL || '';
   const flow = inspection.flow;
 
   lines.push('');
@@ -185,12 +209,14 @@ function formatFlowInspection(inspection, instanceURL) {
   lines.push('');
   lines.push('⚡ FLOW STRUCTURE');
   lines.push('─'.repeat(50));
-  const structureLines = formatFlowStructure(inspection);
+  const structureLines = await formatFlowStructure(inspection, ctx);
   lines.push(...structureLines);
-  // Note limitation for V1/subflows without payload detail
-  if (!inspection.payload || Object.keys(inspection.payload).length === 0) {
+  // Note limitation only when we couldn't reconstruct detail from the payload OR the gzip fallback
+  const hasPayload = inspection.payload && Object.keys(inspection.payload).length > 0;
+  const hasDecodedLogic = (inspection.flowLogicInstances || []).some(l => l._decodedValues);
+  if (!hasPayload && !hasDecodedLogic) {
     lines.push('');
-    lines.push('  (step detail limited — this flow lacks a V2 payload)');
+    lines.push('  (step detail limited — no flow definition data available)');
   }
 
   lines.push('');
@@ -254,15 +280,15 @@ function inferFlowVersion(inspection) {
   return 'Unset';
 }
 
-function formatFlowStructure(inspection) {
+async function formatFlowStructure(inspection, ctx) {
   const payload = inspection.payload;
   if (Object.keys(payload).length > 0) {
-    return formatFlowStructureFromPayload(payload);
+    return formatFlowStructureFromPayload(payload, ctx);
   }
   return formatFlowStructureFallback(inspection);
 }
 
-function formatFlowStructureFromPayload(payload) {
+async function formatFlowStructureFromPayload(payload, ctx) {
   const childUIDs = new Set();
 
   function markChildren(items) {
@@ -312,10 +338,10 @@ function formatFlowStructureFromPayload(payload) {
   const lines = [];
   let stepNum = 1;
 
-  function walk(steps, indent) {
+  async function walk(steps, indent) {
     for (const step of steps) {
       const pad = '    '.repeat(indent);
-      lines.push(...formatStepLine(stepNum, pad, step));
+      lines.push(...await formatStepLine(stepNum, pad, step, ctx));
       stepNum++;
 
       if (step.stepType !== 'logic') continue;
@@ -332,11 +358,11 @@ function formatFlowStructureFromPayload(payload) {
         });
       }
       children.sort((a, b) => a.order - b.order);
-      walk(children, indent + 1);
+      await walk(children, indent + 1);
     }
   }
 
-  walk(roots, 0);
+  await walk(roots, 0);
   return lines;
 }
 
@@ -351,7 +377,7 @@ function formatFlowStructureFallback(inspection) {
         getStringField(action, 'display_text'),
         'Action',
       );
-      steps.push({ order: parseOrderField(action), text: name });
+      steps.push({ order: parseOrderField(action), text: name, comment: getStringField(action, 'comment') });
     }
   }
 
@@ -363,7 +389,12 @@ function formatFlowStructureFallback(inspection) {
         getStringField(logic, 'display_text'),
         'Logic',
       );
-      steps.push({ order: parseOrderField(logic), text: name });
+      steps.push({
+        order: parseOrderField(logic),
+        text: name,
+        comment: getStringField(logic, 'comment'),
+        decoded: logic._decodedValues || null,
+      });
     }
   }
 
@@ -385,15 +416,65 @@ function formatFlowStructureFallback(inspection) {
     return ['  (no steps found)'];
   }
 
-  return steps.map((step, i) => `${i + 1}. ${step.text}`);
+  const lines = [];
+  steps.forEach((step, i) => {
+    const num = `${i + 1}.`;
+    // Decoded gzip values carry the same input detail as a V2 payload
+    if (step.decoded && (step.text === 'If' || step.text === 'Else If')) {
+      let condition = '';
+      let conditionLabel = '';
+      if (Array.isArray(step.decoded.inputs)) {
+        for (const raw of step.decoded.inputs) {
+          if (!raw || typeof raw !== 'object') continue;
+          const inputName = getStringField(raw, 'name');
+          if (inputName === 'condition') {
+            condition = firstNonEmpty(getStringField(raw, 'displayValue'), getStringField(raw, 'value'));
+          }
+          if (inputName === 'condition_name') {
+            conditionLabel = firstNonEmpty(getStringField(raw, 'displayValue'), getStringField(raw, 'value'));
+          }
+        }
+      }
+      let displayText = step.text;
+      if (conditionLabel) {
+        displayText = `${step.text}: ${conditionLabel}`;
+      } else if (condition && condition.length < 60) {
+        displayText = `${step.text}: ${condition}`;
+      }
+      lines.push(`  ${num} ${displayText}`);
+      if (condition && condition.length >= 60 && !conditionLabel) {
+        lines.push(`     Condition: ${condition}`);
+      }
+    } else if (step.decoded && step.text === 'Set Flow Variables') {
+      lines.push(`  ${num} ${step.text}`);
+      const vars = step.decoded.variables || step.decoded.flowVariables;
+      if (Array.isArray(vars) && vars.length > 0) {
+        lines.push(`     Variables Set:`);
+        for (const raw of vars) {
+          if (!raw || typeof raw !== 'object') continue;
+          const varName = getStringField(raw, 'name');
+          const varValue = firstNonEmpty(getStringField(raw, 'displayValue'), getStringField(raw, 'value'));
+          if (!varName) continue;
+          lines.push(varValue ? `       • ${varName} = ${varValue}` : `       • ${varName}`);
+        }
+      }
+    } else {
+      lines.push(`  ${num} ${step.text}`);
+    }
+    if (step.comment) {
+      lines.push(`     Annotation: ${step.comment}`);
+    }
+  });
+
+  return lines;
 }
 
-function formatStepLine(stepNum, pad, step) {
+async function formatStepLine(stepNum, pad, step, ctx) {
   switch (step.stepType) {
     case 'logic':
       return formatLogicStep(stepNum, pad, step.data);
     case 'subflow':
-      return formatSubFlowStep(stepNum, pad, step.data);
+      return formatSubFlowStep(stepNum, pad, step.data, ctx);
     default:
       return formatActionStep(stepNum, pad, step.data);
   }
@@ -425,8 +506,9 @@ function formatActionStep(stepNum, pad, action) {
     }
   }
 
+  const showsTableSuffix = tableName && (actionName === 'Update Record' || actionName === 'Create or Update Record');
   let actionDisplay = actionName;
-  if (tableName && actionName === 'Update Record') {
+  if (showsTableSuffix) {
     actionDisplay = actionName + ' - ' + tableName;
   }
 
@@ -441,7 +523,7 @@ function formatActionStep(stepNum, pad, action) {
     for (const raw of action.inputs) {
       if (!raw || typeof raw !== 'object') continue;
       const inputName = getStringField(raw, 'name');
-      if (inputName === 'table_name') continue;
+      if (inputName === 'table_name' && showsTableSuffix) continue;
 
       let inputValue = firstNonEmpty(getStringField(raw, 'displayValue'), getStringField(raw, 'value'));
       if (!inputValue) continue;
@@ -461,7 +543,7 @@ function formatActionStep(stepNum, pad, action) {
   return lines;
 }
 
-function formatSubFlowStep(stepNum, pad, subFlow) {
+export async function formatSubFlowStep(stepNum, pad, subFlow, ctx) {
   const lines = [];
   const subFlowName = firstNonEmpty(
     getNestedString(subFlow, 'subFlowType', 'fName'),
@@ -479,7 +561,43 @@ function formatSubFlowStep(stepNum, pad, subFlow) {
     lines.push(`${pad}${stepNum}. ↪ ${subFlowName}`);
   }
 
-  lines.push(`${pad}   jsn flows "${subFlowName}"`);
+  // Recurse into the subflow when depth allows and we haven't already seen it.
+  // Note: `subflowSysId` on the instance is a snapshot id (sys_hub_flow_snapshot),
+  // NOT the flow id. The embedded `subFlow.parentFlow` is the real flow sys_id.
+  const subflowSysId = firstNonEmpty(
+    getNestedString(subFlow, 'subFlow', 'parentFlow'),
+    getStringField(subFlow, 'subflowSysId'),
+    getNestedString(subFlow, 'subFlow', 'sys_id'),
+    getStringField(subFlow, 'sys_id'),
+  );
+  const depth = ctx?.depth ?? 1;
+  const canRecurse = ctx?.sdk && subflowSysId && depth > 1 && !ctx.visited.has(subflowSysId);
+
+  if (!canRecurse) {
+    if (!subflowSysId) {
+      lines.push(`${pad}   (subflow definition not found)`);
+    } else if (depth <= 1) {
+      lines.push(`${pad}   jsn flows show "${subFlowName}"`);
+    }
+    return lines;
+  }
+
+  ctx.visited.add(subflowSysId);
+  try {
+    const subInspection = await ctx.sdk.inspectFlow(subflowSysId);
+    const subCtx = { ...ctx, depth: depth - 1 };
+    const subLines = await formatFlowStructure(subInspection, subCtx);
+    if (subLines.length === 0) {
+      lines.push(`${pad}   (no steps found)`);
+    } else {
+      const innerPad = pad + '   ';
+      for (const l of subLines) {
+        lines.push(innerPad + l.replace(/^ {2}/, ''));
+      }
+    }
+  } catch (e) {
+    lines.push(`${pad}   (could not load subflow: ${e.message})`);
+  }
   return lines;
 }
 

package/src/sdk.js

@@ -1,5 +1,6 @@
 // ServiceNow REST API client
 
+import { gunzipSync } from 'node:zlib';
 import { errAuth, errAPI, errNetwork } from './errors.js';
 import { getStringField } from './helpers.js';
 
@@ -246,28 +247,51 @@ export class SDKClient {
       flowOutputs: [],
     };
 
-    // 2) Fetch latest flow version
-    const versionQuery = new URLSearchParams();
-    versionQuery.set('sysparm_display_value', 'all');
-    versionQuery.set('sysparm_limit', '1');
-    versionQuery.set('sysparm_query', `flow=${flowSysID}^ORDERBYDESCsys_updated_on`);
-    versionQuery.set('sysparm_fields', 'sys_id,flow,version,payload,sys_updated_on');
-
-    const versionRecords = await this.list('sys_hub_flow_version', versionQuery);
-    if (versionRecords && versionRecords.length > 0) {
-      inspection.version = versionRecords[0];
-      if (!inspection.flow.version) {
-        inspection.flow.version = getStringField(versionRecords[0], 'version');
+    // 2) Prefer the ProcessFlow API — the Flow Designer UI's own source.
+    //    Returns complete structure for both V2 and legacy V1 flows (the
+    //    version payload field is empty for V1 flows).
+    let payloadLoaded = false;
+    try {
+      const pfResponse = await this.request(`${this.baseURL}/api/now/processflow/flow/${flowSysID}`, { method: 'GET' });
+      const pfData = pfResponse?.result?.data;
+      if (pfData && typeof pfData === 'object' && !pfResponse?.result?.errorMessage) {
+        inspection.payload = pfData;
+        if (!inspection.flow.version) {
+          const pfVersion = getStringField(pfData, 'version');
+          if (pfVersion) inspection.flow.version = pfVersion;
+        }
+        hydrateFlowBlocks(inspection.payload);
+        extractPayloadData(inspection, inspection.payload);
+        payloadLoaded = true;
       }
+    } catch {
+      // ProcessFlow API may not exist on older instances — fall through
+    }
+
+    // 2b) Fallback: latest flow version payload
+    if (!payloadLoaded) {
+      const versionQuery = new URLSearchParams();
+      versionQuery.set('sysparm_display_value', 'all');
+      versionQuery.set('sysparm_limit', '1');
+      versionQuery.set('sysparm_query', `flow=${flowSysID}^ORDERBYDESCsys_updated_on`);
+      versionQuery.set('sysparm_fields', 'sys_id,flow,version,payload,sys_updated_on');
+
+      const versionRecords = await this.list('sys_hub_flow_version', versionQuery);
+      if (versionRecords && versionRecords.length > 0) {
+        inspection.version = versionRecords[0];
+        if (!inspection.flow.version) {
+          inspection.flow.version = getStringField(versionRecords[0], 'version');
+        }
 
-      const payload = getStringField(versionRecords[0], 'payload');
-      if (payload) {
-        try {
-          const payloadData = JSON.parse(payload);
-          inspection.payload = payloadData;
-          extractPayloadData(inspection, payloadData);
-        } catch {
-          // ignore parse error
+        const payload = getStringField(versionRecords[0], 'payload');
+        if (payload) {
+          try {
+            const payloadData = JSON.parse(payload);
+            inspection.payload = payloadData;
+            extractPayloadData(inspection, payloadData);
+          } catch {
+            // ignore parse error
+          }
         }
       }
     }
@@ -295,15 +319,24 @@ export class SDKClient {
     }
 
     if (!inspection.flowLogicInstances || inspection.flowLogicInstances.length === 0) {
-      const logicTables = ['sys_hub_flow_logic', 'sys_hub_flow_logic_instance_v2'];
-      for (const table of logicTables) {
+      const logicTables = [
+        { table: 'sys_hub_flow_logic', payloadField: 'inputs' },
+        { table: 'sys_hub_flow_logic_instance_v2', payloadField: 'values' },
+      ];
+      for (const { table, payloadField } of logicTables) {
         const logicQuery = new URLSearchParams();
         logicQuery.set('sysparm_display_value', 'all');
         logicQuery.set('sysparm_query', `flow=${flowSysID}^ORDERBYorder`);
-        logicQuery.set('sysparm_fields', 'sys_id,order,name,display_text,comment,parent_ui_id,logic_definition');
+        logicQuery.set('sysparm_fields', `sys_id,order,name,display_text,comment,parent_ui_id,logic_definition,${payloadField}`);
         logicQuery.set('sysparm_limit', '200');
         const records = await this.list(table, logicQuery);
-        if (records) inspection.flowLogicInstances.push(...records);
+        if (records) {
+          for (const rec of records) {
+            const decoded = decodeGzipJson(rec[payloadField]);
+            if (decoded) rec._decodedValues = decoded;
+          }
+          inspection.flowLogicInstances.push(...records);
+        }
       }
       inspection.flowLogicInstances.sort((a, b) => parseOrderField(a) - parseOrderField(b));
     }
@@ -634,8 +667,72 @@ function toMapSlice(v) {
   return v.filter(item => item && typeof item === 'object');
 }
 
+/**
+ * The ProcessFlow API returns flow structure as flat arrays where children
+ * reference their parent logic step via a `parent` / `parent_ui_id` field
+ * (a uiUniqueIdentifier value). The payload-based renderer expects nested
+ * `flowBlock` arrays on each logic instance. Rebuild that nesting here so
+ * both data sources render identically.
+ */
+export function hydrateFlowBlocks(payload) {
+  const blockKeys = ['actionInstances', 'flowLogicInstances', 'subFlowInstances'];
+  const items = [];
+  for (const key of blockKeys) {
+    if (Array.isArray(payload[key])) {
+      for (const item of payload[key]) {
+        if (item && typeof item === 'object') items.push(item);
+      }
+    }
+  }
+  if (items.length === 0) return;
+
+  // If the payload already has nested flowBlock arrays (version-payload
+  // shape), leave it alone.
+  const logicItems = Array.isArray(payload.flowLogicInstances) ? payload.flowLogicInstances : [];
+  if (logicItems.some(l => l && typeof l === 'object' && Array.isArray(l.flowBlock))) return;
+
+  // Build parent → children map keyed by uiUniqueIdentifier
+  const childrenByParent = new Map();
+  for (const item of items) {
+    const parentId = getStringField(item, 'parent_ui_id') || getStringField(item, 'parent');
+    if (!parentId) continue;
+    if (!childrenByParent.has(parentId)) childrenByParent.set(parentId, []);
+    childrenByParent.get(parentId).push(item);
+  }
+
+  // Attach sorted flowBlock to each logic instance
+  for (const logic of logicItems) {
+    if (!logic || typeof logic !== 'object') continue;
+    const uid = getStringField(logic, 'uiUniqueIdentifier');
+    const children = uid ? childrenByParent.get(uid) : null;
+    if (Array.isArray(children) && children.length > 0) {
+      children.sort((a, b) => parseOrderField(a) - parseOrderField(b));
+      logic.flowBlock = children;
+    }
+  }
+}
+
 function parseOrderField(record) {
   const order = getStringField(record, 'order');
   const n = parseInt(order, 10);
   return isNaN(n) ? 0 : n;
 }
+
+/**
+ * Decode a ServiceNow flow-logic "values" field: base64-gzip JSON.
+ * Returns the parsed object, or null when the field is empty / not gzip / unparseable.
+ */
+export function decodeGzipJson(value) {
+  if (!value) return null;
+  const s = (typeof value === 'object' && value !== null)
+    ? (value.value ?? value.display_value ?? '')
+    : String(value);
+  const trimmed = s.trim();
+  if (!trimmed.startsWith('H4sI')) return null; // not gzip base64
+  try {
+    const decoded = gunzipSync(Buffer.from(trimmed, 'base64')).toString('utf-8');
+    return JSON.parse(decoded);
+  } catch {
+    return null;
+  }
+}