@jacebenson/jsn 4.0.3 → 4.0.4

package/package.json

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

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

@@ -53,6 +53,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';
@@ -287,6 +288,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 +390,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/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/dev/domains.js

@@ -0,0 +1,292 @@
+// Domain separation commands — list/show/current/set
+//
+// Domain separation (plugin) adds a `domain` table holding the domain
+// hierarchy. Each domain-separated table's rows carry `sys_domain` +
+// `sys_domain_path`, and queries are auto-filtered to the session domain
+// plus its children. There is NO durable platform-side "current domain"
+// preference a CLI can write (the picker sets the in-memory session only,
+// and `sys_user.domain` is write-protected even for admin). So jsn stores
+// the chosen domain in the active profile and sends it on every request
+// via the `X-Now-Domain` header — the same scoping the platform applies
+// to its own picker sessions.
+
+import { getStringField, interactiveList, assertSafeExactMatch } from '../../helpers.js';
+
+const DETAIL_FIELDS = 'sys_id,name,parent,sys_domain_path,description,active,sys_created_on,sys_updated_on';
+
+/**
+ * Gate: domain separation must be installed. The `domain` table only
+ * exists on instances with the plugin. A single cheap query detects it;
+ * on non-DS instances the API returns "Invalid table domain".
+ */
+export async function isDomainSeparationInstalled(app) {
+  try {
+    const params = new URLSearchParams();
+    params.set('sysparm_limit', '1');
+    params.set('sysparm_fields', 'sys_id,name');
+    await app.sdk.list('domain', params);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function requireDomainSeparation(app) {
+  if (!(await isDomainSeparationInstalled(app))) {
+    const e = new Error('Domain separation is not installed on this instance — the `domain` table does not exist. Install the Domain Separation plugin to use these commands.');
+    e.name = 'NotSupported';
+    throw e;
+  }
+}
+
+/**
+ * Resolve a domain name or sys_id to its sys_id. Throws when not found.
+ */
+export async function resolveDomainSysId(app, domainArg) {
+  assertSafeExactMatch(domainArg);
+  const params = new URLSearchParams();
+  params.set('sysparm_query', `name=${domainArg}`);
+  params.set('sysparm_limit', '1');
+  params.set('sysparm_fields', 'sys_id,name');
+  let records = await app.sdk.list('domain', params);
+  if (records.length === 0) {
+    const p2 = new URLSearchParams();
+    p2.set('sysparm_query', `sys_id=${domainArg}`);
+    p2.set('sysparm_limit', '1');
+    p2.set('sysparm_fields', 'sys_id,name');
+    records = await app.sdk.list('domain', p2);
+  }
+  if (records.length === 0) {
+    throw new Error(`Domain not found: ${domainArg}`);
+  }
+  return getStringField(records[0], 'sys_id');
+}
+
+/**
+ * Interactive domain picker — returns the chosen domain's sys_id, or null
+ * when the user cancels. Used by `domains set` and the setup/modify flows.
+ */
+export async function pickDomain(app) {
+  const picked = await interactiveList({
+    app, table: 'domain', singular: 'domain', columns: ['name', 'sys_domain_path'], labelField: 'name',
+    formatLabel: formatDomainLabel,
+  });
+  if (!picked) return null;
+  return getStringField(picked, 'sys_id');
+}
+
+/** Format a picker label: "Name (path)". */
+export function formatDomainLabel(r) {
+  const path = getStringField(r, 'sys_domain_path');
+  return `${getStringField(r, 'name')}${path ? ` (${path})` : ''}`;
+}
+
+/** Build a rich detail view for a domain record. */
+export async function formatDomainDetail(app, record) {
+  const sysID = getStringField(record, 'sys_id');
+  const name = getStringField(record, 'name');
+  const instance = app.getEffectiveInstance();
+  const link = `${instance}/domain.do?sys_id=${sysID}`;
+
+  // Fetch full record for fields not present on the picked row
+  const params = new URLSearchParams();
+  params.set('sysparm_query', `sys_id=${sysID}`);
+  params.set('sysparm_limit', '1');
+  params.set('sysparm_display_value', 'all');
+  params.set('sysparm_fields', DETAIL_FIELDS);
+  const full = await app.sdk.list('domain', params);
+  const rec = full[0] || record;
+
+  const parent = getStringField(rec, 'parent');
+  const path = getStringField(rec, 'sys_domain_path');
+
+  const lines = [
+    `Domain:   ${name}`,
+    `Path:     ${path || '(root)'}`,
+    `Parent:   ${parent || '(none)'}`,
+    `Active:   ${getStringField(rec, 'active') || 'true'}`,
+    `Created:  ${getStringField(rec, 'sys_created_on')}`,
+    `Updated:  ${getStringField(rec, 'sys_updated_on')}`,
+    `Link:     ${link}`,
+  ];
+
+  const desc = getStringField(rec, 'description');
+  if (desc) lines.splice(1, 0, `Desc:     ${desc}`);
+
+  return {
+    sys_id: sysID,
+    name,
+    parent,
+    sys_domain_path: path,
+    _formatted: lines.join('\n'),
+  };
+}
+
+export function domainsCmd(wrap) {
+  return {
+    command: 'domains [subcommand]',
+    aliases: ['domain', 'dom'],
+    describe: 'Manage domains (domain separation)',
+    builder: (yargs) => {
+      return yargs
+        .command({
+          command: 'list',
+          aliases: ['ls'],
+          describe: 'List domains (hierarchy + paths)',
+          builder: (y) => y
+            .option('query', { type: 'string', describe: 'Encoded query (e.g. "nameLIKEACME")' })
+            .option('columns', { alias: ['c', 'fields'], type: 'string', describe: 'Comma-separated columns' })
+            .option('limit', { alias: 'l', type: 'number', default: 50, describe: 'Max records' }),
+          handler: wrap(async (argv, app) => {
+            await requireDomainSeparation(app);
+            const columns = argv.columns ? argv.columns.split(',') : ['name', 'parent', 'sys_domain_path'];
+            const query = argv.query || '';
+
+            const picked = await interactiveList({
+              app, table: 'domain', singular: 'domain', columns, limit: argv.limit, query, labelField: 'name',
+              formatLabel: formatDomainLabel,
+            });
+            if (picked === undefined) return; // user cancelled
+            if (picked) {
+              const detail = await formatDomainDetail(app, picked);
+              return app.ok(detail, { summary: `Domain: ${getStringField(picked, 'name')}` });
+            }
+
+            const params = new URLSearchParams();
+            params.set('sysparm_limit', String(argv.limit));
+            params.set('sysparm_display_value', 'all');
+            params.set('sysparm_fields', ['sys_id', ...columns].join(','));
+            const q = argv.query ? argv.query + '^ORDERBYsys_domain_path' : 'ORDERBYsys_domain_path';
+            params.set('sysparm_query', q);
+            const records = await app.sdk.list('domain', params);
+            app.ok({
+              table: 'domain',
+              count: records.length,
+              columns,
+              records: records.map(r => formatDomainListRecord(r, columns)),
+              context: { instance_url: app.getEffectiveInstance() },
+            }, { summary: `${records.length} domain(s)` });
+          }),
+        })
+        .command({
+          command: 'show <domain>',
+          aliases: ['get'],
+          describe: 'Show a domain by name or sys_id',
+          builder: (y) => y
+            .positional('domain', {
+              describe: 'Domain name (e.g. ACME) or sys_id',
+              type: 'string',
+            }),
+          handler: wrap(async (argv, app) => {
+            await requireDomainSeparation(app);
+            assertSafeExactMatch(argv.domain);
+            let records;
+            // Try by name first, then by sys_id
+            for (const queryField of ['name', 'sys_id']) {
+              const params = new URLSearchParams();
+              params.set('sysparm_query', `${queryField}=${argv.domain}`);
+              params.set('sysparm_limit', '1');
+              params.set('sysparm_display_value', 'all');
+              records = await app.sdk.list('domain', params);
+              if (records.length > 0) break;
+            }
+            if (!records || records.length === 0) {
+              throw new Error(`Domain not found: ${argv.domain}`);
+            }
+            const detail = await formatDomainDetail(app, records[0]);
+            app.ok(detail, { summary: `Domain ${argv.domain}` });
+          }),
+        })
+        .command({
+          command: 'current',
+          describe: 'Show the configured domain for this profile',
+          handler: wrap(async (argv, app) => {
+            await requireDomainSeparation(app);
+            const domain = app._profileDomain(app.config);
+            if (!domain) {
+              app.ok({ domain: '', scoping: 'none' }, {
+                summary: 'No domain configured — requests are not domain-scoped',
+              });
+              return;
+            }
+            // Resolve the configured value to a display name if it's a sys_id
+            let label = domain;
+            try {
+              const params = new URLSearchParams();
+              params.set('sysparm_query', `sys_id=${domain}`);
+              params.set('sysparm_limit', '1');
+              params.set('sysparm_fields', 'sys_id,name');
+              const records = await app.sdk.list('domain', params);
+              if (records.length > 0) label = `${getStringField(records[0], 'name')} (${domain})`;
+            } catch { /* non-fatal — show raw value */ }
+            app.ok({ domain, scoping: 'X-Now-Domain header' }, {
+              summary: `Configured domain: ${label}`,
+            });
+          }),
+        })
+        .command({
+          command: 'set [domain]',
+          describe: 'Set the configured domain for this profile (interactive picker when run bare; omit to clear)',
+          handler: wrap(async (argv, app) => {
+            await requireDomainSeparation(app);
+            let domainArg = argv.domain;
+            if (!domainArg) {
+              const picked = await pickDomain(app);
+              if (!picked) return; // cancelled or non-interactive
+              domainArg = picked;
+            } else if (domainArg.toLowerCase() === 'none' || domainArg.toLowerCase() === 'clear') {
+              app.setDomain('');
+              app.ok({ domain: '' }, { summary: 'Domain cleared — requests are no longer domain-scoped' });
+              return;
+            }
+
+            const sysID = await resolveDomainSysId(app, domainArg);
+            app.setDomain(sysID);
+            app.ok({ domain: sysID, name: domainArg }, {
+              summary: `Configured domain: ${domainArg} — all requests scoped to it`,
+            });
+          }),
+        });
+    },
+    handler: async (argv) => {
+      if (!argv._[1]) {
+        const app = argv.app;
+        let installed = false;
+        try {
+          if (app && app.sdk) installed = await isDomainSeparationInstalled(app);
+        } catch {
+          installed = false;
+        }
+        if (!installed) {
+          if (app && app.sdk) {
+            console.log('Domain separation is not installed on this instance.');
+            console.log('Install the Domain Separation plugin to manage domains.');
+          } else {
+            console.log('No instance configured — run "jsn auth login <instance>" first.');
+          }
+          return;
+        }
+        console.log('Manage ServiceNow domains (domain separation).\n');
+        console.log('Commands:');
+        console.log('  list            List domains (hierarchy + paths)');
+        console.log('  show <domain>   Show a domain');
+        console.log('  current         Show the configured domain for this profile');
+        console.log('  set  [domain]   Configure the domain for this profile (picker when bare; "clear" to unset)');
+        console.log('\nDomains are applied per-request via the X-Now-Domain header —');
+        console.log('the platform filters every query to the domain and its children.');
+        console.log('Run "jsn domains <command> --help" for details.');
+      }
+    },
+  };
+}
+
+/** Flat display record for list mode (keeps the JSON payload small). */
+function formatDomainListRecord(r, columns) {
+  const out = {};
+  for (const c of columns) {
+    const v = getStringField(r, c);
+    out[c] = v;
+  }
+  out.sys_id = getStringField(r, 'sys_id');
+  return out;
+}