@jacebenson/jsn 4.0.1 → 4.0.3

package/README.md

@@ -14,11 +14,27 @@ Node.js 18+. macOS, Linux, Windows.
 
 The install also copies an AI agent skill file to `~/.agents/skills/servicenow/SKILL.md`.
 
+### Install from GitHub (test unreleased builds)
+
+To test a branch or the freshly merged `main` before it's published to npm:
+
+```bash
+npm install -g github:jacebenson/jsn#main        # merged but not yet tagged
+npm install -g github:jacebenson/jsn#<branch>    # any PR/feature branch
+```
+
+Go back to the released version with:
+
+```bash
+npm install -g @jacebenson/jsn
+```
+
+**Note:** git installs build `better-sqlite3` (docs search) from source, so the machine needs build tools (Python, make, a C++ compiler).
+
 ## Quick Start
 
 ```bash
-jsn setup                                    # Interactive first-time setup
-jsn auth login https://dev12345.service-now.com
+jsn setup                                    # Interactive: add, switch, remove, modify instances
 jsn incidents list --query "priority=1"      # Critical incidents
 ```
 
@@ -64,17 +80,23 @@ Run `jsn` for the full grouped list. Commands are organized by ServiceNow domain
 
 Every command supports `--json`, `--query`, and `--help`.
 
-## Profiles (instances)
+## Instances
 
 Switch between instances without re-authenticating.
 
 ```bash
-jsn auth login https://dev12345.service-now.com
-jsn auth status
-jsn auth switch dev12345
+jsn setup                    # Interactive: add, switch, remove, or modify instances
+jsn auth status              # Dashboard — auth state, read-only 🔒, skip-confirmations ⚡
 ```
 
-Add another instance with `jsn auth login <name-or-url>` — run bare for an interactive picker.
+`jsn setup` is the human front door — one command, interactive menu. For scripts and CI, use the atomic commands:
+
+```bash
+jsn auth login https://dev12345.service-now.com   # Add + authenticate (scripted)
+jsn auth refresh                                  # Manually refresh the OAuth token
+jsn auth switch dev12345                          # Flip the active profile (scripted)
+jsn auth modify dev12345                          # Toggle read-only / skip confirmations
+```
 
 ## Output Formats
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "4.0.1",
+  "version": "4.0.3",
   "description": "A command-line interface for ServiceNow that follows the Unix philosophy: simple, composable, and scriptable.",
   "type": "module",
   "bin": {
@@ -8,9 +8,9 @@
   },
   "main": "src/cli.js",
   "scripts": {
-    "test": "NODE_OPTIONS=--require=./suppress-warnings.cjs node --test $(find test -name '*.test.js')",
+    "test": "node --experimental-test-module-mocks --test $(find test -name '*.test.js')",
     "lint": "npx eslint src/ bin/ test/",
-    "start": "NODE_OPTIONS=--require=./suppress-warnings.cjs node bin/jsn.js",
+    "start": "node bin/jsn.js",
     "tag-reminder": "node scripts/tag-reminder.js",
     "release": "node scripts/release.js"
   },
@@ -42,7 +42,6 @@
   },
   "files": [
     "bin/jsn.js",
-    "suppress-warnings.cjs",
     "src/",
     "skills/",
     "scripts/",

package/src/commands/auth.js

@@ -23,6 +23,37 @@ export function resolveInstanceArg(arg, cfg) {
   return normalizeInstanceURL(`${trimmed}.service-now.com`);
 }
 
+/**
+ * Pick a profile by name — interactive search picker when ambiguous,
+ * auto-selects when there's exactly one, throws when none configured.
+ */
+export async function pickProfile(app, message) {
+  const { search } = await import('@inquirer/prompts');
+  const profileNames = Object.keys(app.config.profiles || {});
+  if (profileNames.length === 0) throw errUsage('No profiles configured. Run "jsn setup" first.');
+  if (profileNames.length === 1 || !app.isInteractive()) return profileNames[0];
+  const choices = profileNames.map(name => ({
+    name: `${name} — ${app.config.profiles[name].instance_url}`,
+    value: name,
+  }));
+  return search({
+    message,
+    source: (input) => {
+      const filter = (input || '').toLowerCase();
+      return choices.filter(c => c.name.toLowerCase().includes(filter));
+    },
+  });
+}
+
+/**
+ * Resolve the instance for the wizard: only an EXPLICIT source (env var,
+ * --instance flag/override) pre-fills. The config's default profile must
+ * NOT — the wizard adds an instance, so it always asks otherwise.
+ */
+export function resolveWizardInstance(app, argv = {}) {
+  return process.env.SERVICENOW_INSTANCE_URL || app._overrideInstance || argv.instance || '';
+}
+
 /**
  * Interactive first-run wizard (formerly `jsn setup`).
  *
@@ -39,8 +70,15 @@ export async function loginWizard(app, argv = {}) {
   console.log('Welcome to JSN - ServiceNow CLI');
   console.log();
 
-  let instance = getEffectiveInstance(app.config);
-  if (!instance) {
+  // Ask for the instance URL unless one was explicitly provided (env var,
+  // --instance flag/override). NEVER pre-fill from the config's default
+  // profile — this wizard adds an instance, so it must always ask.
+  // (Regression: setup → Add skipped the URL ask when a default profile
+  // existed, silently re-targeting the default instance.)
+  let instance = resolveWizardInstance(app, argv);
+  if (instance) {
+    instance = normalizeInstanceURL(instance);
+  } else {
     instance = await ask('ServiceNow instance URL (e.g., dev12345.service-now.com): ');
     instance = normalizeInstanceURL(instance);
   }
@@ -165,6 +203,63 @@ async function pickLoginTarget(app) {
   return { addNew: false, name: selected };
 }
 
+/** Per-profile configurable flags (extensible — any boolean on the profile). */
+const PROFILE_FLAGS = [
+  { name: 'Read-only (blocks mutation commands)', value: 'read_only', icon: '🔒' },
+  { name: 'Skip confirmations (deletes run without prompting)', value: 'skip_confirmations', icon: '⚡' },
+];
+
+/**
+ * Toggle a per-profile configuration flag (read_only / skip_confirmations).
+ * Interactive flag picker when no flag passed; testable via argv.flag.
+ */
+export async function modifyProfile(app, argv = {}) {
+  const name = argv.name || await pickProfile(app, 'Modify which instance?');
+  const profile = app.config.profiles?.[name];
+  if (!profile) throw new Error(`Profile not found: ${name}`);
+
+  let flag = argv.flag;
+  if (!flag) {
+    const { select } = await import('@inquirer/prompts');
+    flag = await select({
+      message: `Modify ${name} (${profile.instance_url})`,
+      choices: PROFILE_FLAGS.map(f => ({
+        name: `${f.icon} ${f.name}: ${profile[f.value] ? 'on' : 'off'}`,
+        value: f.value,
+      })),
+    });
+  }
+
+  profile[flag] = !profile[flag];
+  await saveConfig(app.config);
+  app.ok({ profile: name, [flag]: profile[flag] },
+    { summary: `${flag} is now ${profile[flag] ? 'ON' : 'off'} for ${name}` });
+}
+
+/**
+ * Delete an instance entry and its stored credentials (shared by the
+ * `auth remove` subcommand and the `jsn setup` hub).
+ */
+export async function removeProfile(app, name) {
+  if (!app.config.profiles[name]) {
+    throw new Error(`Profile not found: ${name}`);
+  }
+  const instance = app.config.profiles[name].instance_url;
+  delete app.config.profiles[name];
+  if (app.config.defaultProfile === name) app.config.defaultProfile = '';
+  if (app.config.activeProfile === name) app.config.activeProfile = '';
+  saveConfig(app.config);
+
+  // Only clear credentials if no other profile uses this instance URL
+  const stillInUse = instance && Object.values(app.config.profiles || {})
+    .some(p => p.instance_url === instance);
+  if (instance && !stillInUse) {
+    app.auth.logout(instance);
+  }
+
+  app.ok({ removed: name }, { summary: `Removed profile: ${name}` });
+}
+
 export function authCmd(wrap) {
   return {
     command: 'auth [subcommand]',
@@ -507,6 +602,18 @@ Examples:
             app.ok({ active_profile: name }, { summary: `Active profile: ${name}` });
           }),
         })
+        .command({
+          command: 'modify [name]',
+          describe: 'Toggle instance configuration (read-only, skip confirmations)',
+          builder: (sub) => sub
+            .positional('name', {
+              describe: 'Profile name to modify',
+              type: 'string',
+            }),
+          handler: wrap(async (argv, app) => {
+            await modifyProfile(app, argv);
+          }),
+        })
         .command({
           command: 'remove [name]',
           describe: 'Delete an instance entry and its stored credentials',
@@ -518,45 +625,9 @@ Examples:
           handler: wrap(async (argv, app) => {
             let name = argv.name;
             if (!name) {
-              const profileNames = Object.keys(app.config.profiles || {});
-              if (profileNames.length === 0) {
-                throw errUsage('No profiles configured. Nothing to remove.');
-              }
-              if (profileNames.length > 1 && app.isInteractive()) {
-                const { search } = await import('@inquirer/prompts');
-                const choices = profileNames.map(profileName => ({
-                  name: `${profileName} — ${app.config.profiles[profileName].instance_url}`,
-                  value: profileName,
-                }));
-                const selected = await search({
-                  message: 'Remove which profile?',
-                  source: (input) => {
-                    const filter = (input || '').toLowerCase();
-                    return choices.filter(c => c.name.toLowerCase().includes(filter));
-                  },
-                });
-                name = selected;
-              } else {
-                name = profileNames[0];
-              }
+              name = await pickProfile(app, 'Remove which instance?');
             }
-            if (!app.config.profiles[name]) {
-              throw new Error(`Profile not found: ${name}`);
-            }
-            const instance = app.config.profiles[name].instance_url;
-            delete app.config.profiles[name];
-            if (app.config.defaultProfile === name) app.config.defaultProfile = '';
-            if (app.config.activeProfile === name) app.config.activeProfile = '';
-            saveConfig(app.config);
-
-            // Only clear credentials if no other profile uses this instance URL
-            const stillInUse = instance && Object.values(app.config.profiles || {})
-              .some(p => p.instance_url === instance);
-            if (instance && !stillInUse) {
-              app.auth.logout(instance);
-            }
-
-            app.ok({ removed: name }, { summary: `Removed profile: ${name}` });
+            await removeProfile(app, name);
           }),
         });
     },
@@ -565,15 +636,11 @@ Examples:
       console.log('');
       console.log('Available subcommands:');
       console.log('  login <url|name>  Log in / add an instance (picker when run bare)');
-      console.log('  status            Show auth status for all profiles');
-      console.log('  switch <name>     Switch the active profile');
       console.log('  refresh           Refresh the access token');
-      console.log('  logout            Clear credentials (keeps the instance entry)');
-      console.log('  remove <name>     Delete an instance entry and its credentials');
+      console.log('  status            Show auth status for all profiles');
       console.log('');
+      console.log('Tip: "jsn setup" is the interactive manager — add, switch, remove, or modify instances.');
       console.log('Run "jsn auth <command> --help" for details.');
-      console.log('');
-      console.log('Tip: "jsn auth login" is the only command you need to add an instance.');
     },
   };
 }

package/src/commands/dev/flows.js

@@ -307,6 +307,11 @@ async function formatFlowStructure(inspection, ctx) {
     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);
@@ -314,6 +319,48 @@ 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
@@ -657,6 +704,10 @@ export function formatActionStep(stepNum, pad, action, ctx) {
       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/records.js

@@ -1,4 +1,4 @@
-import { formatRecordForDisplay, buildQuerySuffix, parseDataArg, getStringField, interactiveList, resolveFieldsParam, checkDerivedFields, confirmDelete } from '../helpers.js';
+import { formatRecordForDisplay, buildQuerySuffix, parseDataArg, getStringField, interactiveList, resolveFieldsParam, checkDerivedFields, confirmDelete, assertSafeExactMatch } from '../helpers.js';
 
 const tableDefaultColumns = {
   incident: ['number', 'short_description', 'priority', 'state', 'assigned_to'],

package/src/commands/setup.js

@@ -1,25 +1,61 @@
-import { loginWizard } from './auth.js';
+import { loginWizard, modifyProfile, removeProfile, pickProfile } from './auth.js';
+import { setActiveProfile } from '../config.js';
+import { errUsage } from '../errors.js';
 
-// `jsn setup` is kept as a hidden compatibility alias for `jsn auth login`.
-// The wizard lives in auth.js (loginWizard) so there is exactly ONE code path
-// for first-run onboarding — this command can never drift out of sync.
+/** Interactive hub: what do you want to do? Returns 'add' | 'switch' | 'remove' | 'modify'. */
+export async function authHubMenu() {
+  const { select } = await import('@inquirer/prompts');
+  return select({
+    message: 'What would you like to do?',
+    choices: [
+      { name: 'Add a new instance', value: 'add' },
+      { name: 'Switch to a different instance', value: 'switch' },
+      { name: 'Remove an instance', value: 'remove' },
+      { name: 'Modify an instance', value: 'modify' },
+    ],
+  });
+}
+
+/**
+ * Dispatch a hub action to the shared operation. Kept separate from the
+ * handler so routing is testable without invoking inquirer prompts.
+ */
+export async function dispatchSetupAction(app, argv, action) {
+  if (action === 'add') {
+    const result = await loginWizard(app, argv);
+    app.ok({ setup: true, ...result }, { summary: 'Setup complete' });
+  } else if (action === 'switch') {
+    const name = await pickProfile(app, 'Switch to which instance?');
+    await setActiveProfile(app.config, name);
+    app.ok({ active_profile: name }, { summary: `Active profile: ${name}` });
+  } else if (action === 'remove') {
+    const name = await pickProfile(app, 'Remove which instance?');
+    await removeProfile(app, name);
+  } else { // modify
+    await modifyProfile(app, argv);
+  }
+}
+
+// `jsn setup` is the interactive front door for managing instances.
+// The granular, scriptable surface lives under `jsn auth` — this command
+// dispatches to the SAME functions (loginWizard, setActiveProfile,
+// removeProfile, modifyProfile) so the two surfaces can never drift.
 export function setupCmd(wrap) {
   return {
     command: 'setup',
-    describe: 'Interactive first-time setup (use "jsn auth login")',
-    hidden: true, // legacy alias for `jsn auth login` — works but hidden from help
-    builder: (yargs) => {
-      return yargs
-        .option('read-only', {
-          describe: 'Mark profile as read-only (blocks mutation commands)',
-          type: 'boolean',
-          default: false,
-        });
-    },
+    describe: 'Set up and manage your ServiceNow instances (interactive)',
     handler: wrap(async (argv, app) => {
-      console.log('Note: "jsn setup" is now "jsn auth login". Running the same wizard...\n');
-      const result = await loginWizard(app, argv);
-      app.ok({ setup: true, ...result }, { summary: 'Setup complete' });
+      if (!app.isInteractive()) {
+        throw errUsage('"jsn setup" is interactive. Use the specific commands:\n  jsn auth login <instance>\n  jsn auth refresh\n  jsn auth status');
+      }
+      const profileNames = Object.keys(app.config.profiles || {});
+      if (profileNames.length === 0) {
+        const result = await loginWizard(app, argv);
+        app.ok({ setup: true, ...result }, { summary: 'Setup complete' });
+        return;
+      }
+      const action = await authHubMenu();
+      await dispatchSetupAction(app, argv, action);
     }),
   };
 }

package/src/help.js

@@ -107,7 +107,8 @@ const DATA_COMMANDS = [
 ];
 
 const CONFIG_COMMANDS = [
-  { name: 'auth', desc: 'Authentication (login, status, switch, refresh, logout, remove)' },
+  { name: 'setup', desc: 'Set up and manage instances (interactive: add, switch, remove, modify)' },
+  { name: 'auth', desc: 'Authentication (login, refresh, status)' },
   { name: 'updatesets', desc: 'Update sets (set, create, export)' },
   { name: 'scopes', desc: 'Application scopes' },
 ];

package/suppress-warnings.cjs

@@ -1,13 +0,0 @@
-// Suppresses the node:sqlite ExperimentalWarning on Node 22.x.
-// Loaded via NODE_OPTIONS=--require before the main ESM entry point.
-
-const original = process.emitWarning;
-process.emitWarning = function emitWarning(warning, ...args) {
-  const message = typeof warning === 'string'
-    ? warning
-    : (warning?.message || '');
-  if (message.includes('SQLite')) {
-    return;
-  }
-  return original.apply(this, [warning, ...args]);
-};