@jacebenson/jsn 4.1.0 → 4.2.1

package/src/commands/auth.js

@@ -1,7 +1,66 @@
 import { getEffectiveInstance, normalizeInstanceURL, saveConfig, setActiveProfile, setProfile } from '../config.js';
 import { errUsage } from '../errors.js';
+import { declareCapabilities } from '../capabilities.js';
 import process from 'node:process';
 
+// Auth manages local credentials/profiles — runs without a configured
+// instance. (Not in the daily-check skip-list: legacy behavior checks for
+// updates here.)
+declareCapabilities('auth', { noInstance: true });
+
+/**
+ * Render the `jsn auth status` styled (TTY) view: one line per profile with
+ * default marker, auth ✓/✗, 🔒 read_only, ⚡ skip_confirmations, ✅/⚠️
+ * live-verification, and stale-last-seen hints.
+ *
+ * This view logic lives in the auth command — NOT in src/output.js — and is
+ * shipped to the OutputWriter as `data._formatted` (the documented escape
+ * hatch for command-curated visuals; see the interface comment in
+ * src/output.js). The `summary` line is folded into the formatted string
+ * because the writer suppresses opts.summary when _formatted is present.
+ * Golden-pinned by test/auth.test.js ("auth status styled output").
+ */
+export function renderAuthStatus(result, summary) {
+  let out = summary ? `${summary}\n\n` : '';
+  const profiles = Array.isArray(result.profiles) ? result.profiles : [];
+  if (profiles.length > 0) {
+    out += '\n';
+    for (const p of profiles) {
+      const prefix = p.default ? '* ' : '  ';
+      const authIcon = p.authenticated ? '✓' : '✗';
+
+      // Show verified status if we got one
+      let verifiedStr = '';
+      if (p.verified === true) {
+        verifiedStr = ' ✅';
+      } else if (p.verified === false) {
+        verifiedStr = ' ⚠️';
+      }
+
+      // Show stale hint if >7 days since last seen
+      let staleStr = '';
+      if (p.stale && p.days_since_last_seen) {
+        staleStr = ` (${p.days_since_last_seen}d ago — may have been released)`;
+      }
+
+      // Show lock icon for read-only profiles
+      const lockIcon = p.read_only ? ' 🔒' : '';
+
+      // Show confirmations-off badge for skip_confirmations profiles
+      const confirmBadge = p.skip_confirmations ? ' ⚡' : '';
+
+      if (p.name) {
+        out += `${prefix}${authIcon} ${p.name} — ${p.instance}${lockIcon}${confirmBadge}${verifiedStr}${staleStr}\n`;
+      } else if (p.username) {
+        out += `${prefix}${authIcon} ${p.instance} (as ${p.username})${lockIcon}${confirmBadge}${verifiedStr}${staleStr}\n`;
+      } else {
+        out += `${prefix}${authIcon} ${p.instance}${lockIcon}${confirmBadge}${verifiedStr}${staleStr}\n`;
+      }
+    }
+  }
+  return out;
+}
+
 /**
  * Resolve a login/logout/refresh argument to a concrete instance URL.
  *
@@ -46,12 +105,15 @@ export async function pickProfile(app, message) {
 }
 
 /**
- * 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.
+ * Resolve the instance for the wizard: only an EXPLICIT source (env var or
+ * a flag-provided override visible on the app session) 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 || '';
+  // 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 || '';
 }
 
 /**
@@ -125,6 +187,18 @@ export async function loginWizard(app, argv = {}) {
   // Set as active profile so subsequent commands know which instance to use
   app.config.activeProfile = profileName;
   app.config.defaultProfile = profileName;
+
+  // Present all connection-level options during setup. Gated on interactivity
+  // so a piped/scripted call never blocks on prompts.
+  const { canPrompt } = await import('../helpers.js');
+  if (canPrompt()) {
+    const { confirm } = await import('@inquirer/prompts');
+    profile.read_only = await confirm({ message: 'Read-only profile (blocks mutation commands)?', default: profile.read_only || false });
+    profile.skip_confirmations = await confirm({ message: 'Skip confirmations (deletes run without prompting)?', default: profile.skip_confirmations || false });
+    profile.include_counts = await confirm({ message: 'Include result totals on list commands?', default: profile.include_counts !== false });
+    console.log('');
+  }
+
   await saveConfig(app.config);
 
   if (!useBasic) {
@@ -237,6 +311,7 @@ async function pickLoginTarget(app) {
 const PROFILE_FLAGS = [
   { name: 'Read-only (blocks mutation commands)', value: 'read_only', icon: '🔒' },
   { name: 'Skip confirmations (deletes run without prompting)', value: 'skip_confirmations', icon: '⚡' },
+  { name: 'Include result totals on list commands', value: 'include_counts', icon: '🔢' },
 ];
 
 /**
@@ -383,6 +458,10 @@ export function authCmd(wrap) {
               describe: 'Skip delete confirmations on this profile (deletes run without prompting)',
               type: 'boolean',
               default: false,
+            })
+            .option('include-counts', {
+              describe: 'Include result totals on list commands (default on; pass --no-include-counts to opt out)',
+              type: 'boolean',
             }),
           handler: wrap(async (argv, app) => {
             let instanceURL;
@@ -485,19 +564,15 @@ Find your instance URL in your browser's address bar when logged into ServiceNow
               username: username || undefined,
               read_only: argv['read-only'] || undefined,
               skip_confirmations: argv['skip-confirmations'] || undefined,
+              include_counts: argv['include-counts'] === true ? true : argv['include-counts'] === false ? false : undefined,
             };
 
             // Re-save OAuth credentials with username now that we have it,
             // so they're keyed by <user>@<instance> for per-user isolation.
-            // Also clean up the old bare-instance key so migration is clean.
+            // The legacy bare-instance key is cleaned up behind the
+            // AuthManager seam (credential-store internals don't leak here).
             if (!argv.password && username) {
-              const { saveCredentials, loadCredentials, deleteCredentials } = await import('../auth.js');
-              const stored = loadCredentials(instanceURL);
-              if (stored && stored.access_token) {
-                stored.username = username;
-                saveCredentials(instanceURL, stored, username);
-                deleteCredentials(instanceURL); // remove bare-instance legacy key
-              }
+              app.auth.migrateLegacyCredential(instanceURL, username);
             }
 
             // Set as default if this is the first one
@@ -598,6 +673,7 @@ Examples:
                 default: instance === defaultInstance,
                 read_only: profile.read_only || false,
                 skip_confirmations: profile.skip_confirmations || false,
+                include_counts: profile.include_counts !== false,
               });
             }
 
@@ -608,7 +684,11 @@ Examples:
               profiles,
             };
 
-            app.ok(result, { summary: `${profiles.length} profile(s)` });
+            const summary = `${profiles.length} profile(s)`;
+            // Ship the styled view as _formatted (see renderAuthStatus); the
+            // OutputWriter prints it verbatim and suppresses the summary.
+            result._formatted = renderAuthStatus(result, summary);
+            app.ok(result, { summary });
 
             // Warn about legacy credentials that need re-authentication
             const legacyProfiles = profiles.filter(p => p.legacy);

package/src/commands/catalog/enrich.js

@@ -0,0 +1,139 @@
+// Catalog item enrichment — pure async data-shaping for `catalogitems show`.
+//
+// Given an sdk handle, an instance URL and an item sys_id, return the
+// enriched item: core fields resolved to display values, flow name resolved
+// through the sys_hub_flow fallback chain, workflow/delivery-plan fallback,
+// and variables grouped by variable set. No yargs, no output formatting —
+// callers own the envelope and rendering.
+
+import { getStringField } from '../../helpers.js';
+
+/**
+ * Fetch a catalog item and assemble the full show envelope.
+ *
+ * @param {object} deps
+ * @param {object} deps.sdk - SDK handle (list/get).
+ * @param {string} deps.instanceUrl - Effective instance URL (for the item link).
+ * @param {string} deps.sysID - sc_cat_item sys_id.
+ * @returns {Promise<{data: object, standalone: Array, setVars: Array, totalVars: number}>}
+ *   data is the envelope payload (no _formatted — the caller attaches it);
+ *   standalone/setVars/totalVars are the raw groupings needed by
+ *   buildCatalogFormatted.
+ */
+export async function enrichCatalogItem({ sdk, instanceUrl, sysID }) {
+  // Use list + display_value=all so reference fields (category, flow) resolve
+  // to readable display values instead of raw sys_ids.
+  const p = new URLSearchParams();
+  p.set('sysparm_query', `sys_id=${sysID}`);
+  p.set('sysparm_limit', '1');
+  p.set('sysparm_display_value', 'all');
+  const items = await sdk.list('sc_cat_item', p);
+  const item = items[0] || null;
+  if (!item) throw new Error(`Not found: ${sysID}`);
+
+  const vp = new URLSearchParams();
+  vp.set('sysparm_query', `cat_item=${sysID}^active=true`);
+  vp.set('sysparm_limit', '100');
+  vp.set('sysparm_display_value', 'all');
+  vp.set('sysparm_fields', 'sys_id,name,question_text,type,order,mandatory,variable_set');
+  const variables = await sdk.list('item_option_new', vp);
+
+  const standalone = [];
+  const setVars = new Map();
+  for (const v of variables) {
+    const vs = getStringField(v, 'variable_set');
+    const entry = {
+      name: getStringField(v, 'name'),
+      question_text: getStringField(v, 'question_text'),
+      type: getStringField(v, 'type'),
+      mandatory: getStringField(v, 'mandatory'),
+    };
+    if (vs) {
+      if (!setVars.has(vs)) setVars.set(vs, { name: vs, variables: [] });
+      setVars.get(vs).variables.push(entry);
+    } else {
+      standalone.push(entry);
+    }
+  }
+  const totalVars = standalone.length + Array.from(setVars.values()).reduce((a, s) => a + s.variables.length, 0);
+
+  // Resolve flow name
+  let flowName = '', flowCmd = '';
+  const flowVal = item.flow_designer_flow;
+  if (flowVal?.value) {
+    const fn = getStringField(item, 'flow_designer_flow');
+    if (fn === flowVal.value) {
+      try { const fr = await sdk.get('sys_hub_flow', flowVal.value); flowName = getStringField(fr, 'name') || ''; } catch { flowName = fn; }
+    } else { flowName = fn; }
+    flowCmd = `jsn flows show ${flowVal.value}`;
+  }
+  const wfName = getStringField(item, 'workflow') || '';
+  const wfID = item.workflow?.value || '';
+  const planName = getStringField(item, 'delivery_plan') || getStringField(item, 'execution_plan') || '';
+
+  const data = {
+    name: getStringField(item, 'name'),
+    short_description: getStringField(item, 'short_description'),
+    category: getStringField(item, 'category'),
+    active: getStringField(item, 'active'),
+    url: `${instanceUrl}/sc_cat_item.do?sys_id=${sysID}`,
+    flow: flowName || undefined,
+    flow_cmd: flowCmd || undefined,
+    workflow: wfName || undefined,
+    workflow_cmd: (wfName && wfID) ? `jsn workflows show ${wfID}` : undefined,
+    execution_plan: planName || undefined,
+    variables: totalVars > 0 ? {
+      count: totalVars,
+      standalone: standalone.map(v => ({ label: v.question_text || v.name, type: v.type, mandatory: String(v.mandatory) === 'true' })),
+      sets: Array.from(setVars.values()).map(s => ({ name: s.name, variables: s.variables.map(v => ({ label: v.question_text || v.name, type: v.type, mandatory: String(v.mandatory) === 'true' })) })),
+    } : undefined,
+  };
+
+  return { data, standalone, setVars: Array.from(setVars.values()), totalVars };
+}
+
+/**
+ * Styled-mode rendering of an enriched catalog item. Kept verbatim from the
+ * original catalog.js — the output layer is being reworked elsewhere, so this
+ * stays byte-identical for now.
+ */
+export function buildCatalogFormatted(data, standalone, setVars, totalVars) {
+  const lines = [];
+  lines.push(`${data.name} (sc_cat_item)`);
+  lines.push('');
+  lines.push('─ Details ─');
+  if (data.short_description) lines.push(`  short_description:  ${data.short_description}`);
+  if (data.category) lines.push(`  category:  ${data.category}`);
+  lines.push(`  active:  ${data.active}`);
+  if (data.url) lines.push(`  url:  ${data.url}`);
+  if (data.execution_plan) lines.push(`  execution_plan:  ${data.execution_plan}`);
+  lines.push('');
+  if (data.flow) {
+    lines.push('─ Flow ─');
+    lines.push(`  ${data.flow}`);
+    if (data.flow_cmd) lines.push(`  → ${data.flow_cmd}`);
+    lines.push('');
+  }
+  if (data.workflow) {
+    lines.push('─ Workflow ─');
+    lines.push(`  ${data.workflow}`);
+    if (data.workflow_cmd) lines.push(`  → ${data.workflow_cmd}`);
+    lines.push('');
+  }
+  if (totalVars > 0) {
+    lines.push('─ Catalog Variables ─');
+    for (const v of standalone) {
+      const label = v.question_text || v.name;
+      lines.push(`  ${label}:  ${v.type}${String(v.mandatory) === 'true' ? ' (mandatory)' : ''}`);
+    }
+    for (const s of setVars) {
+      lines.push(`  [${s.name}]`);
+      for (const v of s.variables) {
+        const label = v.question_text || v.name;
+        lines.push(`    ${label}:  ${v.type}${String(v.mandatory) === 'true' ? ' (mandatory)' : ''}`);
+      }
+    }
+    lines.push('');
+  }
+  return lines.join('\n');
+}

package/src/commands/catalog.js

@@ -1,4 +1,9 @@
-import { getStringField, interactiveList, assertSafeExactMatch } from '../helpers.js';
+import { getStringField, interactiveList, resolveItemOptionType } from '../helpers.js';
+import { resolveSysId } from '../resolve-record.js';
+import { declareCapabilities } from '../capabilities.js';
+import { enrichCatalogItem, buildCatalogFormatted } from './catalog/enrich.js';
+
+declareCapabilities('catalogitems', { mutationSubcommands: ['create'] });
 
 export function catalogCmd(wrap) {
   return {
@@ -24,16 +29,7 @@ export function catalogCmd(wrap) {
             if (argv.variables) {
               let varsObj;
               try { varsObj = JSON.parse(argv.variables); } catch { throw new Error('--variables must be valid JSON'); }
-              let itemSysID = argv.name;
-              if (!/^[a-f0-9]{32}$/i.test(itemSysID)) {
-                const sp = new URLSearchParams();
-                sp.set('sysparm_query', `name=${itemSysID}`);
-                sp.set('sysparm_limit', '1');
-                sp.set('sysparm_fields', 'sys_id');
-                const items = await app.sdk.list('sc_cat_item', sp);
-                if (items.length === 0) throw new Error(`Not found: ${itemSysID}`);
-                itemSysID = items[0].sys_id?.value || items[0].sys_id;
-              }
+              const itemSysID = await resolveSysId(app.sdk, { table: 'sc_cat_item', identifier: argv.name, matchField: 'name', resource: 'Catalog item' });
               const endpoint = `${app.sdk.baseURL}/api/sn_sc/servicecatalog/items/${itemSysID}/submit_produce`;
               const result = await app.sdk.request(endpoint, { method: 'POST', body: JSON.stringify({ variables: varsObj }) });
               const reqID = result?.result?.sys_id || result?.result?.number || '';
@@ -71,9 +67,8 @@ export function catalogCmd(wrap) {
                   const label = parts.length >= 3 ? parts[parts.length - 1] : parts[0];
                   const sysName = parts[0].replace(/[^a-zA-Z0-9_]/g, '_').toLowerCase();
                   try {
-                    const typeMap = { string: '6', multilinetext: '2', select: '3', date: '4', datetime: '5', reference: '8', checkbox: '12', email: '11' };
                     await app.sdk.create('item_option_new', {
-                      name: sysName, question_text: label, type: typeMap[typeName] || '6',
+                      name: sysName, question_text: label, type: resolveItemOptionType(typeName),
                       order: (varCount + 1) * 100, cat_item: itemID, mandatory: true, active: true,
                     });
                     varCount++;
@@ -148,17 +143,7 @@ export function catalogCmd(wrap) {
           describe: 'Show a catalog item',
           handler: wrap(async (argv, app) => {
             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');
-              p.set('sysparm_fields', 'sys_id');
-              const results = await app.sdk.list('sc_cat_item', p);
-              if (results.length === 0) throw new Error(`Not found: ${id}`);
-              id = results[0].sys_id?.value || results[0].sys_id;
-            }
+            const id = await resolveSysId(app.sdk, { table: 'sc_cat_item', identifier: argv.id, matchField: 'name', resource: 'Catalog item' });
             await showItem(app, id);
           }),
         });
@@ -175,77 +160,15 @@ export function catalogCmd(wrap) {
 }
 
 async function showItem(app, sysID) {
-  // Use list + display_value=all so reference fields (category, flow) resolve
-  // to readable display values instead of raw sys_ids.
-  const p = new URLSearchParams();
-  p.set('sysparm_query', `sys_id=${sysID}`);
-  p.set('sysparm_limit', '1');
-  p.set('sysparm_display_value', 'all');
-  const items = await app.sdk.list('sc_cat_item', p);
-  const item = items[0] || null;
-  if (!item) throw new Error(`Not found: ${sysID}`);
-
-  const vp = new URLSearchParams();
-  vp.set('sysparm_query', `cat_item=${sysID}^active=true`);
-  vp.set('sysparm_limit', '100');
-  vp.set('sysparm_display_value', 'all');
-  vp.set('sysparm_fields', 'sys_id,name,question_text,type,order,mandatory,variable_set');
-  const variables = await app.sdk.list('item_option_new', vp);
-
-  const standalone = [];
-  const setVars = new Map();
-  for (const v of variables) {
-    const vs = getStringField(v, 'variable_set');
-    const entry = {
-      name: getStringField(v, 'name'),
-      question_text: getStringField(v, 'question_text'),
-      type: getStringField(v, 'type'),
-      mandatory: getStringField(v, 'mandatory'),
-    };
-    if (vs) {
-      if (!setVars.has(vs)) setVars.set(vs, { name: vs, variables: [] });
-      setVars.get(vs).variables.push(entry);
-    } else {
-      standalone.push(entry);
-    }
-  }
-  const totalVars = standalone.length + Array.from(setVars.values()).reduce((a, s) => a + s.variables.length, 0);
-
-  // Resolve flow name
-  let flowName = '', flowCmd = '';
-  const flowVal = item.flow_designer_flow;
-  if (flowVal?.value) {
-    const fn = getStringField(item, 'flow_designer_flow');
-    if (fn === flowVal.value) {
-      try { const fr = await app.sdk.get('sys_hub_flow', flowVal.value); flowName = getStringField(fr, 'name') || ''; } catch { flowName = fn; }
-    } else { flowName = fn; }
-    flowCmd = `jsn flows show ${flowVal.value}`;
-  }
-  const wfName = getStringField(item, 'workflow') || '';
-  const wfID = item.workflow?.value || '';
-  const planName = getStringField(item, 'delivery_plan') || getStringField(item, 'execution_plan') || '';
-
-  const data = {
-    name: getStringField(item, 'name'),
-    short_description: getStringField(item, 'short_description'),
-    category: getStringField(item, 'category'),
-    active: getStringField(item, 'active'),
-    url: `${app.getEffectiveInstance()}/sc_cat_item.do?sys_id=${sysID}`,
-    flow: flowName || undefined,
-    flow_cmd: flowCmd || undefined,
-    workflow: wfName || undefined,
-    workflow_cmd: (wfName && wfID) ? `jsn workflows show ${wfID}` : undefined,
-    execution_plan: planName || undefined,
-    variables: totalVars > 0 ? {
-      count: totalVars,
-      standalone: standalone.map(v => ({ label: v.question_text || v.name, type: v.type, mandatory: String(v.mandatory) === 'true' })),
-      sets: Array.from(setVars.values()).map(s => ({ name: s.name, variables: s.variables.map(v => ({ label: v.question_text || v.name, type: v.type, mandatory: String(v.mandatory) === 'true' })) })),
-    } : undefined,
-  };
+  const { data, standalone, setVars, totalVars } = await enrichCatalogItem({
+    sdk: app.sdk,
+    instanceUrl: app.getEffectiveInstance(),
+    sysID,
+  });
 
   // Styled-mode rendering (non-enumerable so JSON output stays clean)
   Object.defineProperty(data, '_formatted', {
-    value: buildCatalogFormatted(data, standalone, Array.from(setVars.values()), totalVars),
+    value: buildCatalogFormatted(data, standalone, setVars, totalVars),
     enumerable: false,
     configurable: true,
   });
@@ -257,44 +180,3 @@ async function showItem(app, sysID) {
     ],
   });
 }
-
-function buildCatalogFormatted(data, standalone, setVars, totalVars) {
-  const lines = [];
-  lines.push(`${data.name} (sc_cat_item)`);
-  lines.push('');
-  lines.push('─ Details ─');
-  if (data.short_description) lines.push(`  short_description:  ${data.short_description}`);
-  if (data.category) lines.push(`  category:  ${data.category}`);
-  lines.push(`  active:  ${data.active}`);
-  if (data.url) lines.push(`  url:  ${data.url}`);
-  if (data.execution_plan) lines.push(`  execution_plan:  ${data.execution_plan}`);
-  lines.push('');
-  if (data.flow) {
-    lines.push('─ Flow ─');
-    lines.push(`  ${data.flow}`);
-    if (data.flow_cmd) lines.push(`  → ${data.flow_cmd}`);
-    lines.push('');
-  }
-  if (data.workflow) {
-    lines.push('─ Workflow ─');
-    lines.push(`  ${data.workflow}`);
-    if (data.workflow_cmd) lines.push(`  → ${data.workflow_cmd}`);
-    lines.push('');
-  }
-  if (totalVars > 0) {
-    lines.push('─ Catalog Variables ─');
-    for (const v of standalone) {
-      const label = v.question_text || v.name;
-      lines.push(`  ${label}:  ${v.type}${String(v.mandatory) === 'true' ? ' (mandatory)' : ''}`);
-    }
-    for (const s of setVars) {
-      lines.push(`  [${s.name}]`);
-      for (const v of s.variables) {
-        const label = v.question_text || v.name;
-        lines.push(`    ${label}:  ${v.type}${String(v.mandatory) === 'true' ? ' (mandatory)' : ''}`);
-      }
-    }
-    lines.push('');
-  }
-  return lines.join('\n');
-}