@jacebenson/jsn 4.0.2 → 4.0.4

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.2",
+  "version": "4.0.4",
   "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/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

@@ -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);
   }
@@ -113,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();
@@ -165,6 +233,121 @@ 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: '⚡' },
+];
+
+/**
+ * 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,
+    });
+    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];
+  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]',
@@ -463,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,
@@ -507,6 +707,22 @@ Examples:
             app.ok({ active_profile: name }, { summary: `Active profile: ${name}` });
           }),
         })
+        .command({
+          command: 'modify [name]',
+          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);
+          }),
+        })
         .command({
           command: 'remove [name]',
           describe: 'Delete an instance entry and its stored credentials',
@@ -518,45 +734,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 +745,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.');
     },
   };
 }