@jacebenson/jsn 4.0.0 → 4.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "4.0.0",
+  "version": "4.0.2",
   "description": "A command-line interface for ServiceNow that follows the Unix philosophy: simple, composable, and scriptable.",
   "type": "module",
   "bin": {
@@ -32,6 +32,7 @@
     "chalk": "^5.4.1",
     "cli-table3": "^0.6.5",
     "gray-matter": "^4.0.3",
+    "turndown": "^7.2.4",
     "yargs": "^17.7.2"
   },
   "devDependencies": {

package/skills/servicenow/SKILL.md

@@ -14,7 +14,7 @@ compatibility: |
   Works with Claude Code, OpenCode, Cursor, and agentskills-compatible tools.
 metadata:
   author: jacebenson
-  version: "3.1.1"
+  version: "4.0.0"
   repository: https://github.com/jacebenson/jsn
 ---
 
@@ -69,7 +69,7 @@ Pick the most specific tool for the job. **Never default to eval** — it's the
 | **Access** | `acls`, `b4rules`, `roles`, `groups`, `users` |
 | **UX** | `forms` (section/element layout), `lists`, `clientscripts`, `uipolicies` |
 | **Data** | `tables`, `columns`, `includes`, `logs`, `properties`, `records` |
-| **Config** | `setup`, `auth`, `profiles`, `updatesets`, `scopes` |
+| **Config** | `setup`, `auth`, `updatesets`, `scopes` |
 | **Docs** | `docs sync`, `docs status`, `docs search`, `docs serve` |
 | **Developer** | `eval`, `rest`, `skill`, `version` |
 

package/src/auth.js

@@ -7,19 +7,34 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
-import { execSync } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
 import { password as passwordPrompt } from '@inquirer/prompts';
 import { globalConfigDir, normalizeInstanceURL } from './config.js';
 import { errAuth } from './errors.js';
 
 // ─── Credential key helpers ───
 
+/**
+ * Sanitize an instance URL into a filesystem/arg-safe key part.
+ *
+ * Whitelist approach (issue #143 findings #2/#3): first map the `://`
+ * protocol separator to `_` exactly as the Go version's encoding does
+ * (so existing keyring keys like `https_dev437538.service-now.com` keep
+ * matching), then drop everything outside [a-zA-Z0-9._-]. Blacklist
+ * stripping of just `/` and `:` left quotes, `$()`, backticks, `;`,
+ * spaces, and backslashes — which broke out of double-quoted shell args
+ * in keyring calls and, on Windows, out of path.join() credential dirs.
+ */
+export function sanitizeKeyPart(instance) {
+  return instance.replace(/:\/\//g, '_').replace(/[^a-zA-Z0-9._-]/g, '_');
+}
+
 /**
  * Build a compound key for credential storage: <username>@<instance>
  * When username is omitted (legacy), just the normalized instance URL is used.
  */
 function credKey(instance, username) {
-  const normalized = instance.replace(/:\/\//g, '_').replace(/\//g, '_').replace(/:/g, '_');
+  const normalized = sanitizeKeyPart(instance);
   if (!username) return normalized;
   return `${username.replace(/[^a-zA-Z0-9._@-]/g, '_')}@${normalized}`;
 }
@@ -29,7 +44,7 @@ function credKey(instance, username) {
 function pkceStatePath(instance) {
   const dir = path.join(globalConfigDir(), 'pkce');
   fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-  const filename = instance.replace(/:\/\//g, '_').replace(/\//g, '_').replace(/:/g, '_') + '.json';
+  const filename = sanitizeKeyPart(instance) + '.json';
   return path.join(dir, filename);
 }
 
@@ -133,8 +148,11 @@ function buildAuthURL(instanceURL, clientID, pkce) {
 
 function keyringLookup(key) {
   try {
-    const result = execSync(
-      `secret-tool lookup ${KEYRING_ATTR_SERVICE} ${KEYRING_SERVICE} ${KEYRING_ATTR_USERNAME} "${key}"`,
+    // execFileSync with an arg array — no shell, so `key` can never
+    // break out into command injection (issue #143 finding #2).
+    const result = execFileSync(
+      'secret-tool',
+      ['lookup', KEYRING_ATTR_SERVICE, KEYRING_SERVICE, KEYRING_ATTR_USERNAME, key],
       { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf-8' }
     );
     const trimmed = result.trim();
@@ -157,9 +175,10 @@ function keyringLookup(key) {
 
 function keyringStore(key, creds) {
   try {
-    execSync(
-      `secret-tool store --label="Password for '${key}' on '${KEYRING_SERVICE}'" ` +
-      `${KEYRING_ATTR_SERVICE} ${KEYRING_SERVICE} ${KEYRING_ATTR_USERNAME} "${key}"`,
+    execFileSync(
+      'secret-tool',
+      ['store', `--label=Password for '${key}' on '${KEYRING_SERVICE}'`,
+        KEYRING_ATTR_SERVICE, KEYRING_SERVICE, KEYRING_ATTR_USERNAME, key],
       { stdio: ['pipe', 'ignore', 'ignore'], input: JSON.stringify(creds) }
     );
     return true;
@@ -170,8 +189,9 @@ function keyringStore(key, creds) {
 
 function keyringDelete(key) {
   try {
-    execSync(
-      `secret-tool clear ${KEYRING_ATTR_SERVICE} ${KEYRING_SERVICE} ${KEYRING_ATTR_USERNAME} "${key}"`,
+    execFileSync(
+      'secret-tool',
+      ['clear', KEYRING_ATTR_SERVICE, KEYRING_SERVICE, KEYRING_ATTR_USERNAME, key],
       { stdio: 'ignore' }
     );
   } catch {

package/src/cli.js

@@ -5,10 +5,11 @@ import { hideBin } from 'yargs/helpers';
 import process from 'node:process';
 import path from 'node:path';
 import fs from 'node:fs';
-import { loadConfig, getEffectiveInstance, getActiveProfile, globalConfigDir } from './config.js';
+import { loadConfig, getActiveProfile, globalConfigDir } from './config.js';
 import { App } from './app.js';
 import { renderHelp } from './help.js';
 import { isMutationCommand } from './mutations.js';
+import { guardExit } from './errors.js';
 
 // Command modules
 import { setupCmd } from './commands/setup.js';
@@ -94,14 +95,6 @@ export function buildCLI() {
   const cfg = loadConfig();
   const app = new App(cfg);
 
-  // Resolve instance once
-  let effectiveInstance;
-  try {
-    effectiveInstance = getEffectiveInstance(cfg);
-  } catch {
-    effectiveInstance = null;
-  }
-
   return yargs(hideBin(process.argv))
     .scriptName('jsn')
     .usage('Usage: jsn <command> [options]')
@@ -161,8 +154,11 @@ export function buildCLI() {
         if (argv.profile) {
           const profile = (cfg.profiles || {})[argv.profile];
           if (!profile) {
-            process.stderr.write(`Error: Unknown profile "${argv.profile}"\n`);
-            process.exit(1);
+            guardExit(argv, {
+              code: 'unknown_profile',
+              message: `Unknown profile "${argv.profile}"`,
+              hint: 'Run "jsn auth status" to list profiles.',
+            });
           }
           const url = profile.instance_url;
           app._overrideInstance = url;
@@ -193,18 +189,16 @@ export function buildCLI() {
             // requireInstance throws errUsage; format it cleanly (the yargs
             // fail handler re-throws middleware errors, which would print a
             // raw stack trace).
-            process.stderr.write(`Error: ${err.message}\n`);
-            process.exit(1);
+            guardExit(argv, { code: err.code || 'usage', message: err.message, hint: err.hint });
           }
           const profile = getActiveProfile(cfg);
           if (profile?.read_only === true) {
             const name = cfg.activeProfile || cfg.defaultProfile;
-            process.stderr.write(
-              `Error: Profile "${name}" is read-only. Mutations are blocked.\n\n` +
-              'Switch to a write-enabled profile first:\n' +
-              `  jsn auth switch <name>\n`
-            );
-            process.exit(1);
+            guardExit(argv, {
+              code: 'read_only',
+              message: `Profile "${name}" is read-only. Mutations are blocked.`,
+              hint: 'Switch to a write-enabled profile first:\n  jsn auth switch <name>',
+            });
           }
         }
       },

package/src/commands/_ticket.js

@@ -1,7 +1,7 @@
 // Generic command builder for CRUD operations on a ServiceNow table
 // Used by incidents, changes, requests, tasks, and most dev subcommands
 
-import { getStringField, formatRecordForDisplay, buildQuerySuffix, resolveFieldsParam } from '../helpers.js';
+import { getStringField, formatRecordForDisplay, buildQuerySuffix, resolveFieldsParam, confirmDelete, assertSafeExactMatch } from '../helpers.js';
 import { search } from '@inquirer/prompts';
 import { isTTY, FormatAuto } from '../output.js';
 
@@ -86,6 +86,7 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
               }
 
               if (selectedNumber) {
+                assertSafeExactMatch(selectedNumber);
                 const showParams = new URLSearchParams();
                 showParams.set('sysparm_query', `number=${selectedNumber}`);
                 showParams.set('sysparm_display_value', 'all');
@@ -161,6 +162,7 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
           describe: `Show a specific ${displayName}`,
           handler: wrap(async (argv, app) => {
             const number = argv.number;
+            assertSafeExactMatch(number);
             const params = new URLSearchParams();
             params.set('sysparm_query', `number=${number}`);
             params.set('sysparm_display_value', 'all');
@@ -216,6 +218,7 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
             .option('data', { type: 'string', demandOption: true, describe: 'JSON data to update' }),
           handler: wrap(async (argv, app) => {
             const number = argv.number;
+            assertSafeExactMatch(number);
             const recordData = JSON.parse(argv.data);
             const findParams = new URLSearchParams();
             findParams.set('sysparm_query', `number=${number}`);
@@ -237,8 +240,11 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
         .command({
           command: 'delete <number>',
           describe: `Delete a ${displayName}`,
+          builder: (y) => y.option('force', { type: 'boolean', default: false, describe: 'Skip confirmation' }),
           handler: wrap(async (argv, app) => {
             const number = argv.number;
+            await confirmDelete(app, argv, `Delete ${displayName} ${number}`);
+            assertSafeExactMatch(number);
             const findParams = new URLSearchParams();
             findParams.set('sysparm_query', `number=${number}`);
             findParams.set('sysparm_limit', '1');

package/src/commands/auth.js

@@ -57,6 +57,9 @@ export async function loginWizard(app, argv = {}) {
   if (argv['read-only']) {
     profile.read_only = true;
   }
+  if (argv['skip-confirmations']) {
+    profile.skip_confirmations = true;
+  }
 
   const authMethod = await ask('Authentication method (OAuth/Basic) [OAuth]: ');
   const useBasic = authMethod.toLowerCase().startsWith('b');
@@ -192,6 +195,11 @@ export function authCmd(wrap) {
               describe: 'Mark the created profile as read-only (blocks mutation commands)',
               type: 'boolean',
               default: false,
+            })
+            .option('skip-confirmations', {
+              describe: 'Skip delete confirmations on this profile (deletes run without prompting)',
+              type: 'boolean',
+              default: false,
             }),
           handler: wrap(async (argv, app) => {
             let instanceURL;
@@ -293,6 +301,7 @@ Find your instance URL in your browser's address bar when logged into ServiceNow
               auth_method: argv.password ? 'basic' : 'oauth',
               username: username || undefined,
               read_only: argv['read-only'] || undefined,
+              skip_confirmations: argv['skip-confirmations'] || undefined,
             };
 
             // Re-save OAuth credentials with username now that we have it,
@@ -405,6 +414,7 @@ Examples:
                 stale: daysSinceLastSeen > 7,
                 default: instance === defaultInstance,
                 read_only: profile.read_only || false,
+                skip_confirmations: profile.skip_confirmations || false,
               });
             }
 

package/src/commands/catalog.js

@@ -1,4 +1,4 @@
-import { getStringField, interactiveList } from '../helpers.js';
+import { getStringField, interactiveList, assertSafeExactMatch } from '../helpers.js';
 
 export function catalogCmd(wrap) {
   return {
@@ -16,7 +16,7 @@ export function catalogCmd(wrap) {
             .option('short-description', { alias: 'd', type: 'string' })
             .option('category', { alias: 'c', type: 'string' })
             .option('variable', { alias: 'v', type: 'array', describe: 'Variable: "name:type:label"' })
-            .option('variables', { type: 'string', describe: 'JSON for submit_produce: {\"key\":\"value\"}' }),
+            .option('variables', { type: 'string', describe: 'JSON for submit_produce: {"key":"value"}' }),
           handler: wrap(async (argv, app) => {
             app.requireInstance();
 
@@ -150,6 +150,7 @@ export function catalogCmd(wrap) {
             app.requireInstance();
             let id = argv.id;
             if (!/^[a-f0-9]{32}$/i.test(id)) {
+              assertSafeExactMatch(id);
               const p = new URLSearchParams();
               p.set('sysparm_query', `name=${id}`);
               p.set('sysparm_limit', '1');
@@ -215,8 +216,6 @@ async function showItem(app, sysID) {
   const wfName = getStringField(item, 'workflow') || '';
   const wfID = item.workflow?.value || '';
   const planName = getStringField(item, 'delivery_plan') || getStringField(item, 'execution_plan') || '';
-  const planID = item.delivery_plan?.value || item.execution_plan?.value || '';
-
   app.ok({
     name: getStringField(item, 'name'),
     short_description: getStringField(item, 'short_description'),

package/src/commands/dev/_generic.js

@@ -1,6 +1,6 @@
 // Generic dev subcommand builder for table-based CRUD
 
-import { formatRecordForDisplay, getStringField, isHexString, parseDataArg } from '../../helpers.js';
+import { formatRecordForDisplay, getStringField, isHexString, parseDataArg, confirmDelete, assertSafeExactMatch } from '../../helpers.js';
 import { getCurrentUser, getCurrentApplication } from '../../context.js';
 import { paginatedSearch } from '../../paginated-search.js';
 import { isTTY, FormatAuto } from '../../output.js';
@@ -81,7 +81,6 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
   const readOnly = opts.readOnly || false;
   const scopeValidation = opts.scopeValidation || false;
   const extraQuery = opts.extraQuery || '';
-  const formatLabel = opts.formatLabel || null;
   const showSummary = opts.showSummary || ((record, id) => `${singular.charAt(0).toUpperCase() + singular.slice(1)}: ${getStringField(record, 'name') || id}`);
   const showBreadcrumbs = opts.showBreadcrumbs || ((record, id) => {
     const crumbs = [
@@ -120,7 +119,7 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
               totalCount = await app.sdk.aggregateCount(table, extraQuery || '');
             } catch { /* non-critical */ }
 
-            const source = async (term, offset, { signal } = {}) => {
+            const source = async (term, offset, { signal: _signal } = {}) => {
               const params = new URLSearchParams();
               params.set('sysparm_limit', String(limit));
               params.set('sysparm_display_value', 'all');
@@ -150,6 +149,7 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
 
             if (selectedName) {
               const recordName = typeof selectedName === 'object' ? selectedName.value : selectedName;
+              assertSafeExactMatch(recordName);
               const showParams = new URLSearchParams();
               showParams.set('sysparm_query', `name=${recordName}`);
               showParams.set('sysparm_display_value', 'all');
@@ -202,6 +202,7 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
         handler: wrap(async (argv, app) => {
           const id = argv.identifier;
           const queryField = isHexString(id) && id.length === 32 ? 'sys_id' : 'name';
+          assertSafeExactMatch(id);
           const params = new URLSearchParams();
           params.set('sysparm_query', `${queryField}=${id}`);
           params.set('sysparm_limit', '1');
@@ -259,6 +260,7 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
           handler: wrap(async (argv, app) => {
             const id = argv.identifier;
             const queryField = isHexString(id) && id.length === 32 ? 'sys_id' : 'name';
+            assertSafeExactMatch(id);
             const findParams = new URLSearchParams();
             findParams.set('sysparm_query', `${queryField}=${id}`);
             findParams.set('sysparm_limit', '1');
@@ -289,6 +291,7 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
           handler: wrap(async (argv, app) => {
             const id = argv.identifier;
             const queryField = isHexString(id) && id.length === 32 ? 'sys_id' : 'name';
+            assertSafeExactMatch(id);
             const findParams = new URLSearchParams();
             findParams.set('sysparm_query', `${queryField}=${id}`);
             findParams.set('sysparm_limit', '1');
@@ -308,17 +311,7 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
               }
             }
 
-            if (!argv.force && process.stdout.isTTY && process.stdin.isTTY) {
-              const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-              const answer = await new Promise((resolve) => {
-                rl.question(`Delete ${singular} '${recordName}'? (y/N): `, resolve);
-              });
-              rl.close();
-              const response = answer.trim().toLowerCase();
-              if (response !== 'y' && response !== 'yes') {
-                throw new Error('Deletion cancelled');
-              }
-            }
+            await confirmDelete(app, argv, `Delete ${singular} '${recordName}'`);
 
             await app.sdk.delete(table, sysID);
             app.ok({ name: recordName, sys_id: sysID, deleted: true }, { summary: `Deleted ${singular} '${recordName}'` });

package/src/commands/dev/flows.js

@@ -302,6 +302,16 @@ function inferFlowVersion(inspection) {
 }
 
 async function formatFlowStructure(inspection, ctx) {
+  const names = await collectCatalogVarNames(inspection, ctx);
+  if (names.size > 0) {
+    if (!ctx.catalogVarNames) ctx.catalogVarNames = new Map();
+    for (const [k, v] of names) ctx.catalogVarNames.set(k, v);
+  }
+  const labelCache = buildLabelCache(inspection.payload);
+  if (labelCache.size > 0) {
+    if (!ctx.labelCache) ctx.labelCache = new Map();
+    for (const [k, v] of labelCache) ctx.labelCache.set(k, v);
+  }
   const payload = inspection.payload;
   if (Object.keys(payload).length > 0) {
     return formatFlowStructureFromPayload(payload, ctx);
@@ -309,6 +319,146 @@ async function formatFlowStructure(inspection, ctx) {
   return formatFlowStructureFallback(inspection);
 }
 
+/**
+ * The ProcessFlow payload carries a label cache (also serialized as
+ * labelCacheAsJsonString) mapping data-pill names like "<step-uid>.<var>"
+ * to the human labels the Flow Designer UI shows, e.g.
+ * "1 - Get Catalog Variables➛session_title". Build a Map so guid-prefixed
+ * pills can be rendered readably.
+ */
+function buildLabelCache(payload) {
+  const cache = new Map();
+  if (!payload || typeof payload !== 'object') return cache;
+  let entries = payload.label_cache;
+  if (!Array.isArray(entries)) {
+    try {
+      entries = JSON.parse(payload.labelCacheAsJsonString || '[]');
+    } catch {
+      entries = [];
+    }
+  }
+  for (const e of entries) {
+    if (!e || typeof e !== 'object') continue;
+    const name = getStringField(e, 'name');
+    const label = getStringField(e, 'label');
+    if (name && label) cache.set(name, label);
+  }
+  return cache;
+}
+
+const GUID_PILL_RE = /\{\{([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.([^}]+)\}\}/g;
+
+/**
+ * Replace opaque guid-prefixed pills ({{<32-hex-guid>.<var>}}) with their
+ * human label from the payload's label cache. Readable step refs like
+ * {{Created_1.table_name}} are NOT matched and stay raw.
+ */
+function resolveGuidPills(value, labelCache) {
+  if (!labelCache || labelCache.size === 0 || !value) return value;
+  return String(value).replace(GUID_PILL_RE, (m, guid, name) => {
+    const label = labelCache.get(`${guid}.${name}`);
+    return label ? `{{${label}}}` : m;
+  });
+}
+
+/**
+ * ServiceNow serializes catalog variable selections in action inputs as
+ * comma-separated "sys_id:table" pairs (e.g. Get Catalog Variables / Create
+ * Catalog Task steps). The payload carries the source table on the parameter
+ * attributes, but the value itself also names it in each token. Resolve those
+ * sys_ids to readable labels (question_text, falling back to name) with one
+ * batched Table API query per distinct table.
+ */
+async function collectCatalogVarNames(inspection, ctx) {
+  const names = new Map();
+  if (!ctx?.sdk) return names;
+
+  const refs = new Map(); // table -> Set<sys_id>
+  const TOKEN_RE = /([0-9a-f]{32}):([a-z_]+)/g;
+
+  function addRefsFromValue(value) {
+    if (!value) return;
+    for (const m of String(value).matchAll(TOKEN_RE)) {
+      const [, id, table] = m;
+      if (!refs.has(table)) refs.set(table, new Set());
+      refs.get(table).add(id);
+    }
+  }
+
+  function walk(items) {
+    if (!Array.isArray(items)) return;
+    for (const item of items) {
+      if (!item || typeof item !== 'object') continue;
+      if (Array.isArray(item.inputs)) {
+        for (const input of item.inputs) {
+          if (!input || typeof input !== 'object') continue;
+          addRefsFromValue(firstNonEmpty(getStringField(input, 'displayValue'), getStringField(input, 'value')));
+        }
+      }
+      if (Array.isArray(item.flowBlock)) walk(item.flowBlock);
+    }
+  }
+
+  const payload = inspection?.payload;
+  if (payload && typeof payload === 'object') {
+    walk(payload.actionInstances);
+    if (Array.isArray(payload.flowLogicInstances)) {
+      for (const logic of payload.flowLogicInstances) walk(logic?.flowBlock);
+    }
+  }
+  // Fallback table sources may also carry inputs (e.g. decoded logic values)
+  walk(inspection?.actionInstances);
+  if (Array.isArray(inspection?.flowLogicInstances)) {
+    for (const logic of inspection.flowLogicInstances) {
+      if (logic?._decodedValues?.inputs) {
+        for (const input of logic._decodedValues.inputs) {
+          if (!input || typeof input !== 'object') continue;
+          addRefsFromValue(firstNonEmpty(getStringField(input, 'displayValue'), getStringField(input, 'value')));
+        }
+      }
+    }
+  }
+
+  for (const [table, ids] of refs) {
+    const idList = [...ids];
+    for (let i = 0; i < idList.length; i += 100) {
+      const chunk = idList.slice(i, i + 100);
+      try {
+        const params = new URLSearchParams();
+        params.set('sysparm_query', `sys_idIN${chunk.join(',')}`);
+        params.set('sysparm_fields', 'sys_id,name,question_text');
+        params.set('sysparm_display_value', 'all');
+        params.set('sysparm_limit', String(chunk.length));
+        const records = await ctx.sdk.list(table, params);
+        for (const r of records) {
+          const id = getStringField(r, 'sys_id');
+          const label = firstNonEmpty(getStringField(r, 'question_text'), getStringField(r, 'name'));
+          if (id && label) names.set(id, label);
+        }
+      } catch {
+        // resolution failed (no access, deleted record) — leave raw sys_ids
+      }
+    }
+  }
+
+  return names;
+}
+
+/**
+ * Replace catalog variable "sys_id:table" pairs with readable labels when the
+ * resolver map has them. Returns null when the value isn't a catalog-variable
+ * list (so callers keep rendering it raw).
+ */
+function resolveCatalogVarValue(value, catalogVarNames) {
+  if (!catalogVarNames || catalogVarNames.size === 0 || !value) return null;
+  const trimmed = String(value).trim();
+  if (!/^([0-9a-f]{32}:[a-z_]+)(,[0-9a-f]{32}:[a-z_]+)*,?$/.test(trimmed)) return null;
+  return String(value).replace(/([0-9a-f]{32}):[a-z_]+/g, (m, id) => {
+    const label = catalogVarNames.get(id);
+    return label || m;
+  });
+}
+
 async function formatFlowStructureFromPayload(payload, ctx) {
   const childUIDs = new Set();
 
@@ -497,11 +647,11 @@ async function formatStepLine(stepNum, pad, step, ctx) {
     case 'subflow':
       return formatSubFlowStep(stepNum, pad, step.data, ctx);
     default:
-      return formatActionStep(stepNum, pad, step.data);
+      return formatActionStep(stepNum, pad, step.data, ctx);
   }
 }
 
-export function formatActionStep(stepNum, pad, action) {
+export function formatActionStep(stepNum, pad, action, ctx) {
   const lines = [];
   let actionName = firstNonEmpty(
     getNestedString(action, 'actionType', 'fName'),
@@ -549,6 +699,15 @@ export function formatActionStep(stepNum, pad, action) {
       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).
+      const resolvedCatalog = resolveCatalogVarValue(inputValue, ctx?.catalogVarNames);
+      if (resolvedCatalog) inputValue = resolvedCatalog;
+
+      // Opaque guid-prefixed pills ({{<32-hex>.<var>}}) get their human
+      // label from the payload's label cache. Readable step refs stay raw.
+      inputValue = resolveGuidPills(inputValue, ctx?.labelCache);
+
       let label = inputName;
       if (raw.parameter && typeof raw.parameter === 'object') {
         label = firstNonEmpty(getStringField(raw.parameter, 'label'), label);

package/src/commands/dev/forms.js

@@ -22,15 +22,6 @@ function getIntValue(record, key) {
   return 0;
 }
 
-function getBoolValue(record, key) {
-  if (!record || typeof record !== 'object') return false;
-  const val = record[key];
-  if (typeof val === 'boolean') return val;
-  if (typeof val === 'string') return val === 'true';
-  if (typeof val === 'object' && val.value != null) return String(val.value) === 'true';
-  return false;
-}
-
 async function showForm(app, table, viewName) {
   // 1) Look up the view
   const viewParams = new URLSearchParams();
@@ -88,8 +79,6 @@ async function showForm(app, table, viewName) {
 
   sectionsOut.sort((a, b) => a.position - b.position);
 
-  const totalElements = sectionsOut.reduce((sum, s) => sum + s.elements.length, 0);
-
   // Build formatted output
   const lines = [];
   lines.push(`Form: ${table} → ${viewName}`);

package/src/commands/dev/import.js

@@ -20,7 +20,7 @@ export const importCmd = (wrap) => buildDevCmd('import', 'sys_import_set', ['imp
         const rows = await app.sdk.list('sys_import_set_row', rp);
         console.log(`  Import rows: ${rows.length}`);
         console.log(`    → jsn records list --table sys_import_set_row --query "sys_import_set=${sysID}" --limit 200`);
-      } catch (err) {
+      } catch {
         console.log(`  Import rows: (unavailable)`);
       }
     },

package/src/commands/dev/lists.js

@@ -17,7 +17,7 @@ export function listsCmd(wrap) {
           handler: wrap(async (argv, app) => {
             app.requireInstance();
             let table = argv.table;
-            let viewSysID = null;
+            let viewSysID;
 
             // If no table, pick one interactively
             if (!table) {
@@ -76,7 +76,7 @@ export function listsCmd(wrap) {
             const table = argv.table;
 
             // Resolve view sys_id
-            let viewSysID = '';
+            let viewSysID;
             const vp = new URLSearchParams();
             vp.set('sysparm_limit', '1'); vp.set('sysparm_fields', 'sys_id');
             vp.set('sysparm_query', `name=${argv.view}^name=${table}`);

package/src/commands/docs/community-sources.json

@@ -0,0 +1,18 @@
+{
+  "sources": [
+    {
+      "name": "maik-skoddow-knowledge-sources",
+      "author": "Maik Skoddow",
+      "author_url": "https://www.servicenow.com/community/user/viewprofilepage/user-id/116698",
+      "url": "https://www.servicenow.com/community/training-and-certifications/knowledge-sources-to-go/ta-p/2310130",
+      "expand": true
+    },
+    {
+      "name": "mark-roethof-experiences",
+      "author": "Mark Roethof",
+      "author_url": "https://www.servicenow.com/community/user/viewprofilepage/user-id/201738",
+      "url": "https://www.servicenow.com/community/developer-blog/456-articles-blogs-videos-podcasts-share-projects-experiences/ba-p/2292127",
+      "expand": true
+    }
+  ]
+}