@jacebenson/jsn 4.0.3 → 4.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "4.0.3",
+  "version": "4.1.0",
   "description": "A command-line interface for ServiceNow that follows the Unix philosophy: simple, composable, and scriptable.",
   "type": "module",
   "bin": {
@@ -29,8 +29,6 @@
     "@inquirer/core": "^10.1.0",
     "@inquirer/prompts": "^7.5.1",
     "better-sqlite3": "^13.0.3",
-    "chalk": "^5.4.1",
-    "cli-table3": "^0.6.5",
     "gray-matter": "^4.0.3",
     "turndown": "^7.2.4",
     "yargs": "^17.7.2"

package/src/app.js

@@ -3,7 +3,7 @@
 import { AuthManager } from './auth.js';
 import { SDKClient } from './sdk.js';
 import { OutputWriter, FormatAuto, FormatJSON, FormatMarkdown, FormatQuiet, FormatStyled } from './output.js';
-import { getEffectiveInstance, normalizeInstanceURL } from './config.js';
+import { getEffectiveInstance, normalizeInstanceURL, saveConfig } from './config.js';
 import { extractProfileName } from './helpers.js';
 import { getCurrentUser, getCurrentApplication, getCurrentUpdateSet } from './context.js';
 import { errUsage, errAuth } from './errors.js';
@@ -20,7 +20,9 @@ export class App {
 
     const instance = getEffectiveInstance(cfg);
     if (instance) {
-      this.sdk = new SDKClient(instance, this.auth);
+      this.sdk = new SDKClient(instance, this.auth, {
+        domain: this._profileDomain(cfg),
+      });
     }
 
     this.context = {
@@ -202,9 +204,29 @@ export class App {
     const normalizedUrl = normalizeInstanceURL(url);
     if (normalizedUrl) {
       this._overrideInstance = normalizedUrl;
-      this.sdk = new SDKClient(normalizedUrl, this.auth);
+      this.sdk = new SDKClient(normalizedUrl, this.auth, {
+        domain: this._profileDomain(this.config),
+      });
     }
   }
+
+  /** Read the configured domain for the active profile (empty = no scoping). */
+  _profileDomain(cfg) {
+    const name = cfg.activeProfile || cfg.defaultProfile;
+    if (name && cfg.profiles[name]) {
+      return cfg.profiles[name].domain || '';
+    }
+    return '';
+  }
+
+  /** Set (or clear with '') the domain for the active profile. */
+  setDomain(domain) {
+    const name = this.config.activeProfile || this.config.defaultProfile;
+    if (!name) throw errUsage('No active profile to set a domain on');
+    if (!this.config.profiles[name]) this.config.profiles[name] = {};
+    this.config.profiles[name].domain = domain || '';
+    return saveConfig(this.config);
+  }
 }
 
 function resolveFormat(fmt) {

package/src/cli.js

@@ -10,6 +10,7 @@ import { App } from './app.js';
 import { renderHelp } from './help.js';
 import { isMutationCommand } from './mutations.js';
 import { guardExit } from './errors.js';
+import { FormatJSON } from './output.js';
 
 // Command modules
 import { setupCmd } from './commands/setup.js';
@@ -53,6 +54,7 @@ import { formsCmd } from './commands/dev/forms.js';
 import { listsCmd } from './commands/dev/lists.js';
 import { updateSetsCmd } from './commands/dev/updatesets.js';
 import { scopesCmd } from './commands/dev/scopes.js';
+import { domainsCmd } from './commands/dev/domains.js';
 import { evalCmd } from './commands/dev/eval.js';
 import { restCmd } from './commands/dev/rest.js';
 import { logsCmd } from './commands/dev/logs.js';
@@ -85,6 +87,19 @@ function wrap(handler) {
         process.stderr.write(`Error (system): ${err.message}\n`);
         process.exit(3);
       }
+      if (err.code === 'confirmation_required') {
+        // Structured error for AI agents / piped consumers: emit the
+        // JSON envelope on stdout (where tooling reads) so the agent can
+        // surface the decision to its user or re-run with --force.
+        const app = argv.app;
+        if (app && app.output.effectiveFormat() === FormatJSON) {
+          app.err(err);
+        } else {
+          process.stderr.write(`Error: ${err.message}\n`);
+          if (err.hint) process.stderr.write(`\n${err.hint}\n`);
+        }
+        process.exit(1);
+      }
       process.stderr.write(`Error: ${err.message}\n`);
       process.exit(1);
     }
@@ -287,6 +302,7 @@ export function buildCLI() {
     .command(authCmd(wrap))
     .command(updateSetsCmd(wrap))
     .command(scopesCmd(wrap))
+    .command(domainsCmd(wrap))
     // CORE
     .command(incidentsCmd(wrap))
     .command(changesCmd(wrap))
@@ -388,7 +404,7 @@ export function buildCLI() {
           }
           process.exit(0);
         }
-        process.stdout.write(renderHelp() + '\n');
+        process.stdout.write(renderHelp(loadConfig()) + '\n');
         process.exit(0);
       }
       process.stderr.write(msg + '\n');

package/src/commands/_ticket.js

@@ -1,9 +1,9 @@
 // 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, confirmDelete, assertSafeExactMatch } from '../helpers.js';
+import { getStringField, formatRecordForDisplay, buildQuerySuffix, resolveFieldsParam, confirmDelete, assertSafeExactMatch, canPrompt } from '../helpers.js';
 import { search } from '@inquirer/prompts';
-import { isTTY, FormatAuto } from '../output.js';
+import { FormatAuto } from '../output.js';
 
 export function buildTicketCommands(table, displayName, alias, defaultColumns, stateMap, iconFn, wrap) {
   return {
@@ -28,7 +28,7 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
             const offset = argv.offset;
 
             // Interactive picker in TTY with auto format and no explicit query/offset
-            const isInteractive = isTTY(process.stdout) && isTTY(process.stdin);
+            const isInteractive = canPrompt();
             if (isInteractive && app.output.getFormat() === FormatAuto && !query && offset === 0) {
               const pickerColumns = ['sys_id', 'number', 'short_description', 'state', 'assigned_to'];
               const pickerParams = new URLSearchParams();

package/src/commands/auth.js

@@ -151,6 +151,36 @@ export async function loginWizard(app, argv = {}) {
       }
       console.log('Login successful!');
       loggedIn = true;
+
+      // Probe domain separation capability once and stamp the profile, so
+      // `jsn domains` (and its help entry) only appear on instances with it.
+      try {
+        const { SDKClient } = await import('../sdk.js');
+        const domainsMod = await import('./dev/domains.js');
+        const sdk = new SDKClient(instance, app.auth);
+        profile.domain_separation = await domainsMod.isDomainSeparationInstalled({ sdk });
+        await setProfile(app.config, profileName, profile);
+
+        // If domain separation is installed, offer to pick a default domain
+        // for the profile — every request will be scoped to it via X-Now-Domain.
+        if (profile.domain_separation) {
+          const { confirm } = await import('@inquirer/prompts');
+          const setDomainNow = await confirm({
+            message: 'Domain separation detected. Configure a domain for this instance?',
+            default: false,
+          });
+          if (setDomainNow) {
+            const domainSysID = await domainsMod.pickDomain({ ...app, sdk });
+            if (domainSysID) {
+              profile.domain = domainSysID;
+              await setProfile(app.config, profileName, profile);
+              console.log('Domain configured.');
+            }
+          }
+        }
+      } catch {
+        // Non-fatal — capability unknown; domains command falls back to probing
+      }
     }
   } else {
     rl.close();
@@ -210,24 +240,82 @@ const PROFILE_FLAGS = [
 ];
 
 /**
- * Toggle a per-profile configuration flag (read_only / skip_confirmations).
- * Interactive flag picker when no flag passed; testable via argv.flag.
+ * Modify a profile: toggle a boolean flag, or set/clear the domain.
+ * Interactive picker when no flag passed; testable via argv.flag/argv.domain.
  */
 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}`);
 
+  // Domain setting path: --domain <name|sys_id|clear>
+  if (argv.domain !== undefined) {
+    if (!profile.domain_separation) {
+      throw new Error(`Domain separation is not installed on ${profile.instance_url} — no domain to configure.`);
+    }
+    if (argv.domain === 'clear' || argv.domain === 'none' || argv.domain === '') {
+      profile.domain = '';
+      await saveConfig(app.config);
+      app.ok({ profile: name, domain: '' }, { summary: `Domain cleared for ${name}` });
+      return;
+    }
+    const { isDomainSeparationInstalled } = await import('./dev/domains.js');
+    const { SDKClient } = await import('../sdk.js');
+    const sdk = new SDKClient(profile.instance_url, app.auth);
+    if (!(await isDomainSeparationInstalled({ sdk }))) {
+      throw new Error(`Domain separation is not installed on ${profile.instance_url}`);
+    }
+    const { resolveDomainSysId } = await import('./dev/domains.js');
+    const sysID = await resolveDomainSysId({ sdk }, argv.domain);
+    profile.domain = sysID;
+    await saveConfig(app.config);
+    app.ok({ profile: name, domain: sysID }, { summary: `Domain set for ${name}` });
+    return;
+  }
+
   let flag = argv.flag;
   if (!flag) {
     const { select } = await import('@inquirer/prompts');
+    const choices = PROFILE_FLAGS.map(f => ({
+      name: `${f.icon} ${f.name}: ${profile[f.value] ? 'on' : 'off'}`,
+      value: f.value,
+    }));
+    if (profile.domain_separation) {
+      choices.push({
+        name: `🌐 Domain: ${profile.domain ? 'set' : 'not set'}`,
+        value: 'domain',
+      });
+    }
+    const { SDKClient } = await import('../sdk.js');
+    const sdk = new SDKClient(profile.instance_url, app.auth);
     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,
-      })),
+      choices,
     });
+    if (flag === 'domain') {
+      const domainsMod = await import('./dev/domains.js');
+      const installed = await domainsMod.isDomainSeparationInstalled({ sdk });
+      if (!installed) {
+        throw new Error(`Domain separation is not installed on ${profile.instance_url}`);
+      }
+      const { confirm } = await import('@inquirer/prompts');
+      const clear = profile.domain
+        ? await confirm({ message: `Domain is set. Clear it?`, default: false })
+        : false;
+      if (clear) {
+        profile.domain = '';
+        await saveConfig(app.config);
+        app.ok({ profile: name, domain: '' }, { summary: `Domain cleared for ${name}` });
+        return;
+      }
+      const sysID = await domainsMod.pickDomain({ ...app, sdk });
+      if (sysID) {
+        profile.domain = sysID;
+        await saveConfig(app.config);
+        app.ok({ profile: name, domain: sysID }, { summary: `Domain set for ${name}` });
+      }
+      return;
+    }
   }
 
   profile[flag] = !profile[flag];
@@ -558,6 +646,23 @@ Examples:
 
             const creds = await app.auth.getCredentialsFor(instanceURL);
             const refreshed = await app.auth.refreshToken(instanceURL, creds);
+
+            // Re-probe domain separation on refresh so the capability flag
+            // stays in sync if the plugin was installed/removed since setup.
+            try {
+              const { SDKClient } = await import('../sdk.js');
+              const { isDomainSeparationInstalled } = await import('./dev/domains.js');
+              const sdk = new SDKClient(instanceURL, app.auth);
+              const hasDS = await isDomainSeparationInstalled({ sdk });
+              const name = app.config.activeProfile || app.config.defaultProfile;
+              if (name && app.config.profiles[name] && app.config.profiles[name].instance_url === instanceURL) {
+                app.config.profiles[name].domain_separation = hasDS;
+                await saveConfig(app.config);
+              }
+            } catch {
+              // Non-fatal — capability probe is best-effort
+            }
+
             app.ok({
               refreshed: true,
               instance: instanceURL,
@@ -604,11 +709,15 @@ Examples:
         })
         .command({
           command: 'modify [name]',
-          describe: 'Toggle instance configuration (read-only, skip confirmations)',
+          describe: 'Toggle instance configuration (read-only, skip confirmations, domain)',
           builder: (sub) => sub
             .positional('name', {
               describe: 'Profile name to modify',
               type: 'string',
+            })
+            .option('domain', {
+              type: 'string',
+              describe: 'Set the domain for this profile (name, sys_id, or "clear")',
             }),
           handler: wrap(async (argv, app) => {
             await modifyProfile(app, argv);

package/src/commands/catalog.js

@@ -175,7 +175,15 @@ export function catalogCmd(wrap) {
 }
 
 async function showItem(app, sysID) {
-  const item = await app.sdk.get('sc_cat_item', 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`);
@@ -216,7 +224,8 @@ 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') || '';
-  app.ok({
+
+  const data = {
     name: getStringField(item, 'name'),
     short_description: getStringField(item, 'short_description'),
     category: getStringField(item, 'category'),
@@ -232,7 +241,60 @@ async function showItem(app, sysID) {
       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,
-  }, {
-    summary: `${getStringField(item, 'name')} — ${totalVars} variable(s)`,
+  };
+
+  // Styled-mode rendering (non-enumerable so JSON output stays clean)
+  Object.defineProperty(data, '_formatted', {
+    value: buildCatalogFormatted(data, standalone, Array.from(setVars.values()), totalVars),
+    enumerable: false,
+    configurable: true,
   });
+
+  app.ok(data, {
+    summary: `${data.name} — ${totalVars} variable(s)`,
+    breadcrumbs: [
+      { action: 'list', cmd: 'jsn catalogitems list', description: 'Back to all catalog items' },
+    ],
+  });
+}
+
+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/dev/_generic.js

@@ -1,9 +1,9 @@
 // Generic dev subcommand builder for table-based CRUD
 
-import { formatRecordForDisplay, getStringField, isHexString, parseDataArg, confirmDelete, assertSafeExactMatch } from '../../helpers.js';
+import { formatRecordForDisplay, getStringField, isHexString, parseDataArg, confirmDelete, assertSafeExactMatch, canPrompt } from '../../helpers.js';
 import { getCurrentUser, getCurrentApplication } from '../../context.js';
 import { paginatedSearch } from '../../paginated-search.js';
-import { isTTY, FormatAuto } from '../../output.js';
+import { FormatAuto } from '../../output.js';
 
 function vowelArticle(word) {
   const first = word.charAt(0).toLowerCase();
@@ -111,7 +111,7 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
           const limit = argv.limit;
 
           // Interactive picker with pagination
-          const interactive = isTTY(process.stdout) && isTTY(process.stdin);
+          const interactive = canPrompt();
           if (interactive && app.output.getFormat() === FormatAuto && !query) {
             // Get total count
             let totalCount = 0;