@jacebenson/jsn 3.4.3 → 4.0.0

package/README.md

@@ -64,17 +64,18 @@ Run `jsn` for the full grouped list. Commands are organized by ServiceNow domain
 
 Every command supports `--json`, `--query`, and `--help`.
 
-## Profiles
+## Profiles (instances)
 
 Switch between instances without re-authenticating.
 
 ```bash
 jsn auth login https://dev12345.service-now.com
-jsn profiles list
-jsn profiles use dev12345
-jsn profiles show
+jsn auth status
+jsn auth switch dev12345
 ```
 
+Add another instance with `jsn auth login <name-or-url>` — run bare for an interactive picker.
+
 ## Output Formats
 
 | Flag | When to use |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "3.4.3",
+  "version": "4.0.0",
   "description": "A command-line interface for ServiceNow that follows the Unix philosophy: simple, composable, and scriptable.",
   "type": "module",
   "bin": {
@@ -28,6 +28,7 @@
   "dependencies": {
     "@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",

package/skills/servicenow/SKILL.md

@@ -44,7 +44,7 @@ All `list` subcommands use a paginated interactive picker in TTY mode:
 2. **Use sys_id for updates** — All update/delete operations require sys_id
 3. **Check auth first** — Run `jsn auth status` before operations
 4. **NEVER logout** — Only run `jsn auth logout` if the user explicitly asks
-5. **Use `--profile <name>`** to target a specific instance, or `jsn profiles use <name>` to change default
+5. **Use `--profile <name>`** to target a specific instance, or `jsn auth switch <name>` to change the default
 6. **Before using `eval` or `rest`** — Ask: *"Is there a more specific jsn command?"* Prefer specific over generic over escape hatch over eval.
 7. **CONFIRM before destructive operations** — Show what will be created/updated/deleted and ask for approval.
 

package/src/app.js

@@ -120,10 +120,15 @@ export class App {
 
     const scopeFormatted = `[${scope}]`;
 
+    // Read-only profiles get a lock badge on every command run, so the
+    // armed safety is always visible (not just in `auth status`).
+    const activeProfile = this.context.profileName ? this.config.profiles[this.context.profileName] : null;
+    const roBadge = activeProfile?.read_only === true ? ' 🔒' : '';
+
     process.stderr.write('# Use `jsn scopes` to change scope, `jsn updatesets set` to change updateset\n');
     process.stderr.write('PROFILE   USER      [SCOPE]           UPDATE SET\n');
 
-    const profileStr = `]8;;${instanceLink}\x07${String(this.context.profileName).padEnd(9)}]8;;\x07`;
+    const profileStr = `\u001b]8;;${instanceLink}\x07${String(this.context.profileName).padEnd(9)}${roBadge}\u001b]8;;\x07`;
     const userStr = `]8;;${userLink}\x07${String(displayUserName).padEnd(9)}]8;;\x07`;
     const scopeStr = `]8;;${scopeLink}\x07${String(scopeFormatted).padEnd(17)}]8;;\x07`;
     const updateSetStr = `]8;;${updateSetLink}\x07${updateSet}]8;;\x07`;
@@ -131,9 +136,7 @@ export class App {
     process.stderr.write(`${profileStr} ${userStr} ${scopeStr} ${updateSetStr}\n\n`);
 
     // ⚠️  Warning if in the Default update set (mutation commands only)
-    const profile = this.context.profileName ? this.config.profiles[this.context.profileName] : null;
-    const isYolo = profile?.yolo === true;
-    if (!isYolo && isMutationCommand(argv) && updateSet && updateSet.toLowerCase().includes('default')) {
+    if (isMutationCommand(argv) && updateSet && updateSet.toLowerCase().includes('default')) {
       const isGlobal = scope === 'global';
       if (isGlobal) {
         // 🔴 HARD WARNING — Global + Default
@@ -150,8 +153,6 @@ export class App {
           '┃                                                        ┃\n' +
           '┃  Or switch to a scoped scope first:                    ┃\n' +
           '┃    jsn scopes list                                 ┃\n' +
-          '┃                                                        ┃\n' +
-          '┃  (Run jsn updatesets yolo to silence this check)    ┃\n' +
           '┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛\x1b[0m\n'
         );
       } else {
@@ -162,7 +163,6 @@ export class App {
           '  ⚠  Default update set in scope [' + scope + ']\n' +
           '  Changes are contained to this scope, but a named\n' +
           '  update set is still recommended for tracking.\n' +
-          '  (Run \x1b[1mjsn updatesets yolo\x1b[22m to silence this warning)\n' +
           '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n' +
           '\x1b[0m' // reset
         );

package/src/auth.js

@@ -58,24 +58,6 @@ function removePKCEState(instance) {
 const DEFAULT_OAUTH_CLIENT_ID = '543e5655f77746a28228c6009a599dfb';
 const REDIRECT_URI = '/sdk-oauth.do';
 
-// ─── WSL detection ───
-
-/**
- * Detect if running under Windows Subsystem for Linux.
- * Reads /proc/version which contains "Microsoft" or "WSL" on WSL.
- */
-let _cachedIsWSL = null;
-async function isWSLEnv() {
-  if (_cachedIsWSL !== null) return _cachedIsWSL;
-  try {
-    const data = fs.readFileSync('/proc/version', 'utf-8');
-    _cachedIsWSL = /microsoft|wsl/i.test(data);
-  } catch {
-    _cachedIsWSL = false;
-  }
-  return _cachedIsWSL;
-}
-
 // ─── Basic auth from environment variables ───
 // SN_USERNAME / SN_PASSWORD — global credentials
 // SN_<INSTANCE>_USERNAME / SN_<INSTANCE>_PASSWORD — instance-specific (e.g. SN_DEV328604_USERNAME)
@@ -390,43 +372,12 @@ export class AuthManager {
     const authURL = buildAuthURL(instanceURL, clientID, pkce);
 
     console.log();
-    console.log('Opening browser for OAuth authentication...');
-    console.log('If the browser does not open automatically, visit:');
+    console.log('Open this URL in your browser to authenticate:');
     console.log(authURL);
     console.log();
-
-    // Try to open browser
-    const open = (await import('node:child_process')).spawn;
-    const platform = process.platform;
-    let cmd, args;
-    if (platform === 'darwin') {
-      cmd = 'open';
-      args = [authURL];
-    } else if (platform === 'win32') {
-      cmd = 'cmd';
-      // Windows: cmd.exe interprets & as a command separator, which truncates
-      // the URL after the first parameter. Passing an empty string as the first
-      // arg to `start` serves as the window title, and spawn auto-quotes the
-      // URL arg, protecting & and other special chars from cmd.exe's parser.
-      args = ['/c', 'start', '', authURL];
-    } else {
-      // WSL detection: check if we're running under Windows Subsystem for Linux
-      // On WSL, xdg-open delegates to cmd.exe /C start <url>, which truncates
-      // on &. We call cmd.exe directly with proper quoting instead.
-      const isWSL = platform === 'linux' && (await isWSLEnv());
-      if (isWSL) {
-        cmd = 'cmd.exe';
-        args = ['/c', 'start', '', authURL];
-      } else {
-        cmd = 'xdg-open';
-        args = [authURL];
-      }
-    }
-    const child = open(cmd, args, { detached: true, stdio: 'ignore' });
-    child.on('error', () => {
-      // Browser open command not available — user will open the URL manually
-    });
-    child.unref();
+    console.log('(The browser is not opened automatically — if a browser tab opens,');
+    console.log(' use the URL above if the opened page shows an error.)');
+    console.log();
 
     console.log('After authenticating in the browser, copy the authorization code shown on the page.');
     console.log('(input is hidden for security — just paste and press Enter)');

package/src/cli.js

@@ -5,7 +5,7 @@ import { hideBin } from 'yargs/helpers';
 import process from 'node:process';
 import path from 'node:path';
 import fs from 'node:fs';
-import { loadConfig, getEffectiveInstance, globalConfigDir } from './config.js';
+import { loadConfig, getEffectiveInstance, getActiveProfile, globalConfigDir } from './config.js';
 import { App } from './app.js';
 import { renderHelp } from './help.js';
 import { isMutationCommand } from './mutations.js';
@@ -13,7 +13,6 @@ import { isMutationCommand } from './mutations.js';
 // Command modules
 import { setupCmd } from './commands/setup.js';
 import { authCmd } from './commands/auth.js';
-import { profilesCmd } from './commands/profiles.js';
 import { recordsCmd } from './commands/records.js';
 import { catalogCmd } from './commands/catalog.js';
 import { incidentsCmd } from './commands/incidents.js';
@@ -176,10 +175,10 @@ export function buildCLI() {
           argv._overrideInstance = argv.instance;
         }
       },
-      // Guard mutation commands when no instance configured
+      // Guard mutation commands: require an instance, block read-only profiles
       (argv) => {
         const cmd = (argv._[0] || '').toString();
-        if (!cmd || ['help', 'version', 'completion', 'setup', 'auth', 'profiles', 'skill', 'docs'].includes(cmd)) {
+        if (!cmd || ['help', 'version', 'completion', 'setup', 'auth', 'skill', 'docs'].includes(cmd)) {
           return;
         }
         // Check for --instance override
@@ -187,11 +186,26 @@ export function buildCLI() {
           app._overrideInstance = argv.instance;
           argv._overrideInstance = argv.instance;
         }
-        // Determine if this is a mutation
-        const subcommand = (argv._[1] || '').toString();
-        const isMutation = isMutationCommand(cmd, subcommand);
-        if (isMutation) {
-          app.requireInstance();
+        if (isMutationCommand(argv)) {
+          try {
+            app.requireInstance();
+          } catch (err) {
+            // requireInstance throws errUsage; format it cleanly (the yargs
+            // fail handler re-throws middleware errors, which would print a
+            // raw stack trace).
+            process.stderr.write(`Error: ${err.message}\n`);
+            process.exit(1);
+          }
+          const profile = getActiveProfile(cfg);
+          if (profile?.read_only === true) {
+            const name = cfg.activeProfile || cfg.defaultProfile;
+            process.stderr.write(
+              `Error: Profile "${name}" is read-only. Mutations are blocked.\n\n` +
+              'Switch to a write-enabled profile first:\n' +
+              `  jsn auth switch <name>\n`
+            );
+            process.exit(1);
+          }
         }
       },
     ])
@@ -277,7 +291,6 @@ export function buildCLI() {
     // CONFIGURATION
     .command(setupCmd(wrap))
     .command(authCmd(wrap))
-    .command(profilesCmd(wrap))
     .command(updateSetsCmd(wrap))
     .command(scopesCmd(wrap))
     // CORE

package/src/commands/auth.js

@@ -1,16 +1,176 @@
-import { getEffectiveInstance, normalizeInstanceURL } from '../config.js';
+import { getEffectiveInstance, normalizeInstanceURL, saveConfig, setActiveProfile, setProfile } from '../config.js';
 import { errUsage } from '../errors.js';
 import process from 'node:process';
 
+/**
+ * Resolve a login/logout/refresh argument to a concrete instance URL.
+ *
+ * gh-style precision: a full URL is used as-is; a bare name is first checked
+ * against known profile names (gh: --hostname), then treated as a ServiceNow
+ * instance name with the canonical `.service-now.com` host appended. This kills
+ * the old trap where `jsn auth login dev99999` silently targeted
+ * `https://dev99999` (a dead host).
+ */
+export function resolveInstanceArg(arg, cfg) {
+  if (!arg) return '';
+  const trimmed = arg.trim();
+  if (/^https?:\/\//i.test(trimmed)) return normalizeInstanceURL(trimmed);
+  const profile = cfg?.profiles?.[trimmed];
+  if (profile?.instance_url) return normalizeInstanceURL(profile.instance_url);
+  // Already looks like a host (has a dot) — add the scheme, nothing else
+  if (trimmed.includes('.')) return normalizeInstanceURL(trimmed);
+  // Bare ServiceNow instance name → canonical host
+  return normalizeInstanceURL(`${trimmed}.service-now.com`);
+}
+
+/**
+ * Interactive first-run wizard (formerly `jsn setup`).
+ *
+ * Walks: instance URL → profile name → auth method → optional OAuth login.
+ * Creates and activates the profile, then returns the result so the caller
+ * decides how to report it. Basic auth saves credentials directly (the OAuth
+ * path has no interactive username/password).
+ */
+export async function loginWizard(app, argv = {}) {
+  const readline = (await import('node:readline')).default;
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (q) => new Promise((resolve) => rl.question(q, resolve));
+
+  console.log('Welcome to JSN - ServiceNow CLI');
+  console.log();
+
+  let instance = getEffectiveInstance(app.config);
+  if (!instance) {
+    instance = await ask('ServiceNow instance URL (e.g., dev12345.service-now.com): ');
+    instance = normalizeInstanceURL(instance);
+  }
+  console.log(`Instance: ${instance}`);
+
+  // Warn if another profile already uses this instance URL
+  const existing = Object.entries(app.config.profiles || {}).find(([, p]) => p.instance_url === instance);
+  if (existing) {
+    console.log(`Note: instance is also used by profile "${existing[0]}".`);
+  }
+
+  const profileName = (await ask('Profile name (default): ')) || 'default';
+  const profile = { instance_url: instance };
+  if (argv['read-only']) {
+    profile.read_only = true;
+  }
+
+  const authMethod = await ask('Authentication method (OAuth/Basic) [OAuth]: ');
+  const useBasic = authMethod.toLowerCase().startsWith('b');
+
+  let loggedIn = false;
+  if (useBasic) {
+    const username = await ask('Username: ');
+    rl.close(); // Close outer readline before askHidden creates its own
+    const { loadCredentials, askHidden, saveCredentials } = await import('../auth.js');
+    const existingCreds = loadCredentials(instance) || loadCredentials(instance, username);
+    if (existingCreds && existingCreds.auth_method === 'basic') {
+      console.log(`Using existing credentials for ${instance}`);
+    } else {
+      const password = await askHidden('Password: ');
+      saveCredentials(instance, { auth_method: 'basic', username, password }, username);
+      console.log('Basic auth credentials saved');
+    }
+    profile.username = username;
+    profile.auth_method = 'basic';
+  } else {
+    profile.auth_method = 'oauth';
+  }
+
+  await setProfile(app.config, profileName, profile);
+  // Set as active profile so subsequent commands know which instance to use
+  app.config.activeProfile = profileName;
+  app.config.defaultProfile = profileName;
+  await saveConfig(app.config);
+
+  if (!useBasic) {
+    const loginNow = await ask('Login now? [Y/n]: ');
+    rl.close();
+    if (!loginNow || loginNow.toLowerCase() !== 'n') {
+      await app.auth.login(instance);
+      // Re-save credentials under <user>@<instance> after verifying username
+      try {
+        const { SDKClient } = await import('../sdk.js');
+        const sdk = new SDKClient(instance, app.auth);
+        const user = await sdk.getCurrentUser();
+        if (user && user.user_name) {
+          const { loadCredentials, saveCredentials } = await import('../auth.js');
+          const stored = loadCredentials(instance);
+          if (stored && stored.access_token) {
+            stored.username = user.user_name;
+            saveCredentials(instance, stored, user.user_name);
+          }
+          profile.username = user.user_name;
+        }
+      } catch {
+        // Non-fatal — token saved, username will be set on next auth login
+      }
+      console.log('Login successful!');
+      loggedIn = true;
+    }
+  } else {
+    rl.close();
+  }
+
+  return { instanceURL: instance, profileName, loggedIn };
+}
+
+/**
+ * gh-faithful login target picker: existing profiles plus an "add a new
+ * instance" row. Typing filters profiles; picking the ＋ row uses what you
+ * typed (or prompts for it).
+ *
+ * Returns { addNew: true, instanceName } or { addNew: false, name }.
+ */
+async function pickLoginTarget(app) {
+  const { search, input } = await import('@inquirer/prompts');
+  const ADD_NEW = '__add_new__';
+  const profileNames = Object.keys(app.config.profiles || {});
+  let lastInput = '';
+  const selected = await search({
+    message: 'Log in to which instance?',
+    source: (term) => {
+      const filter = (term || '').toLowerCase();
+      lastInput = term || '';
+      const profiles = profileNames
+        .filter((name) => {
+          const label = `${name} — ${app.config.profiles[name].instance_url}`.toLowerCase();
+          return !filter || label.includes(filter);
+        })
+        .map((name) => ({
+          name: `${name} — ${app.config.profiles[name].instance_url}`,
+          value: name,
+        }));
+      const addLabel = filter
+        ? `＋ Add "${term.trim()}" as a new instance`
+        : '＋ Add a new instance';
+      return [{ name: addLabel, value: ADD_NEW }, ...profiles];
+    },
+  });
+  if (selected === ADD_NEW) {
+    const typed = lastInput.trim();
+    if (typed) return { addNew: true, instanceName: typed };
+    const name = await input({
+      message: 'ServiceNow instance name or URL (e.g. dev12345):',
+      validate: (v) => (v.trim() ? true : 'Instance name or URL is required'),
+    });
+    return { addNew: true, instanceName: name.trim() };
+  }
+  return { addNew: false, name: selected };
+}
+
 export function authCmd(wrap) {
   return {
-    command: 'auth <subcommand>',
+    command: 'auth [subcommand]',
     describe: 'Manage authentication (OAuth or basic auth via env vars)',
     builder: (yargs) => {
       return yargs
         .command({
           command: 'login [instance]',
-          describe: 'Authenticate with a ServiceNow instance via OAuth',
+          describe: 'Authenticate with a ServiceNow instance (interactive picker when run bare)',
           builder: (sub) => sub
             .option('code', {
               describe: 'Authorization code from browser (bypasses interactive prompt)',
@@ -27,38 +187,42 @@ export function authCmd(wrap) {
             .option('wait-file', {
               describe: 'File path to watch for authorization code (used with --print-url)',
               type: 'string',
+            })
+            .option('read-only', {
+              describe: 'Mark the created profile as read-only (blocks mutation commands)',
+              type: 'boolean',
+              default: false,
             }),
           handler: wrap(async (argv, app) => {
             let instanceURL;
             if (argv.instance) {
-              // Check if it's a profile name first
-              const profiles = app.config.profiles || {};
-              if (profiles[argv.instance] && profiles[argv.instance].instance_url) {
-                instanceURL = normalizeInstanceURL(profiles[argv.instance].instance_url);
+              instanceURL = resolveInstanceArg(argv.instance, app.config);
+            } else if (app.isInteractive()) {
+              // gh-faithful: interactive terminals always get a picker —
+              // existing profiles plus "＋ Add a new instance". Zero profiles
+              // goes straight to the setup wizard.
+              const profileNames = Object.keys(app.config.profiles || {});
+              if (profileNames.length === 0) {
+                const wizard = await loginWizard(app, argv);
+                if (wizard.loggedIn) {
+                  app.ok({ authenticated: true, instance: wizard.instanceURL, profile: wizard.profileName },
+                    { summary: `✓ Authenticated to ${wizard.instanceURL} (profile: ${wizard.profileName})` });
+                } else {
+                  app.ok({ setup: true, instance: wizard.instanceURL, profile: wizard.profileName },
+                    { summary: `Profile "${wizard.profileName}" created for ${wizard.instanceURL}. Run "jsn auth login" to authenticate.` });
+                }
+                return;
+              }
+              const target = await pickLoginTarget(app);
+              if (target.addNew) {
+                instanceURL = resolveInstanceArg(target.instanceName, app.config);
               } else {
-                instanceURL = normalizeInstanceURL(argv.instance);
+                instanceURL = normalizeInstanceURL(app.config.profiles[target.name].instance_url);
               }
             } else {
               instanceURL = getEffectiveInstance(app.config);
               if (!instanceURL) {
-                // Try interactive profile picker
-                const profileNames = Object.keys(app.config.profiles || {});
-                if (profileNames.length > 0 && app.isInteractive()) {
-                  const { search } = await import('@inquirer/prompts');
-                  const choices = profileNames.map(name => ({
-                    name: `${name} — ${app.config.profiles[name].instance_url}`,
-                    value: name,
-                  }));
-                  const selected = await search({
-                    message: 'Select a profile:',
-                    source: (input) => {
-                      const filter = (input || '').toLowerCase();
-                      return choices.filter(c => c.name.toLowerCase().includes(filter));
-                    },
-                  });
-                  instanceURL = normalizeInstanceURL(app.config.profiles[selected].instance_url);
-                } else {
-                  throw errUsage(`Instance URL required.
+                throw errUsage(`Instance URL required.
 
 Examples:
   jsn auth login https://dev12345.service-now.com
@@ -66,7 +230,6 @@ Examples:
   jsn auth login --password https://dev328604.service-now.com
 
 Find your instance URL in your browser's address bar when logged into ServiceNow.`);
-                }
               }
             }
 
@@ -129,6 +292,7 @@ Find your instance URL in your browser's address bar when logged into ServiceNow
               instance_url: instanceURL,
               auth_method: argv.password ? 'basic' : 'oauth',
               username: username || undefined,
+              read_only: argv['read-only'] || undefined,
             };
 
             // Re-save OAuth credentials with username now that we have it,
@@ -169,11 +333,11 @@ Find your instance URL in your browser's address bar when logged into ServiceNow
         })
         .command({
           command: 'logout [instance]',
-          describe: 'Remove stored OAuth credentials',
+          describe: 'Clear stored credentials (keeps the instance entry — use "auth remove" to delete it)',
           handler: wrap(async (argv, app) => {
             let instanceURL;
             if (argv.instance) {
-              instanceURL = normalizeInstanceURL(argv.instance);
+              instanceURL = resolveInstanceArg(argv.instance, app.config);
             } else {
               instanceURL = getEffectiveInstance(app.config);
               if (!instanceURL) {
@@ -240,6 +404,7 @@ Examples:
                 days_since_last_seen: daysSinceLastSeen,
                 stale: daysSinceLastSeen > 7,
                 default: instance === defaultInstance,
+                read_only: profile.read_only || false,
               });
             }
 
@@ -273,13 +438,7 @@ Examples:
           handler: wrap(async (argv, app) => {
             let instanceURL;
             if (argv.instance) {
-              // Check if it's a profile name or URL
-              const profiles = app.config.profiles || {};
-              if (profiles[argv.instance] && profiles[argv.instance].instance_url) {
-                instanceURL = normalizeInstanceURL(profiles[argv.instance].instance_url);
-              } else {
-                instanceURL = normalizeInstanceURL(argv.instance);
-              }
+              instanceURL = resolveInstanceArg(argv.instance, app.config);
             } else {
               instanceURL = getEffectiveInstance(app.config);
               if (!instanceURL) {
@@ -300,17 +459,111 @@ Examples:
               expires_at: refreshed.expires_at,
             }, { summary: `✓ Token refreshed for ${instanceURL}` });
           }),
+        })
+        .command({
+          command: 'switch [name]',
+          describe: 'Switch active profile (gh: auth switch)',
+          builder: (sub) => sub
+            .positional('name', {
+              describe: 'Profile name to activate',
+              type: 'string',
+            }),
+          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. Run "jsn auth login" first.');
+              }
+              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: 'Select a profile:',
+                  source: (input) => {
+                    const filter = (input || '').toLowerCase();
+                    return choices.filter(c => c.name.toLowerCase().includes(filter));
+                  },
+                });
+                name = selected;
+              } else {
+                name = profileNames[0];
+              }
+            }
+            await setActiveProfile(app.config, name);
+            app.ok({ active_profile: name }, { summary: `Active profile: ${name}` });
+          }),
+        })
+        .command({
+          command: 'remove [name]',
+          describe: 'Delete an instance entry and its stored credentials',
+          builder: (sub) => sub
+            .positional('name', {
+              describe: 'Profile name to delete',
+              type: 'string',
+            }),
+          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];
+              }
+            }
+            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}` });
+          }),
         });
     },
     handler: () => {
-      console.log('Manage OAuth authentication for ServiceNow instances.');
+      console.log('Manage authentication for ServiceNow instances.');
       console.log('');
       console.log('Available subcommands:');
-      console.log('  login <url>    Login with OAuth (supports --print-url, --code for CI/CD)');
-      console.log('  status         Show auth status for the active profile');
-      console.log('  refresh        Refresh the access token');
+      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('');
       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/updatesets.js

@@ -164,21 +164,6 @@ export function updateSetsCmd(wrap) {
             });
           }),
         })
-        .command({
-          command: 'yolo',
-          aliases: ['silence'],
-          describe: 'Silence the "Default update set" warning for this profile',
-          handler: wrap(async (argv, app) => {
-            const name = app.context.profileName;
-            if (!name) {
-              throw new Error('No active profile to mark as yolo. Run jsn setup first.');
-            }
-            app.config.profiles[name].yolo = true;
-            const { saveConfig } = await import('../../config.js');
-            saveConfig(app.config);
-            app.ok({ profile: name, yolo: true }, { summary: 'Default update set warning silenced for this profile' });
-          }),
-        })
         .command({
           command: 'export <name>',
           describe: 'Export an update set to XML',
@@ -225,7 +210,6 @@ export function updateSetsCmd(wrap) {
         console.log('  create         Create a new update set (auto-sets as current)');
         console.log('  export <name>  Export an update set to XML');
         console.log('  complete <name>  Mark an update set as complete (coming soon)');
-        console.log('  yolo           Silence the "Default update set" warning');
         console.log('\nRun "jsn updatesets <command> --help" for details.');
         console.log('\nTip: Create an update set first:');
         console.log('  jsn updatesets create --name "My Feature"');

package/src/commands/docs/db.js

@@ -3,7 +3,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
-import { DatabaseSync } from 'node:sqlite';
+import Database from 'better-sqlite3';
 
 const DOCS_DIR_NAME = 'servicenow-cli/docs';
 
@@ -37,7 +37,7 @@ export function ensureDocsCacheDir() {
 export function openDocsDb(opts = {}) {
   const dbPath = opts.dbPath || getDocsDbPath();
   ensureDocsCacheDir();
-  const db = new DatabaseSync(dbPath);
+  const db = new Database(dbPath);
   db.exec('PRAGMA journal_mode = WAL');
   return db;
 }

package/src/commands/docs/search.js

@@ -1,7 +1,7 @@
 // CLI search against the docs SQLite database.
 
 import fs from 'node:fs';
-import { DatabaseSync } from 'node:sqlite';
+import Database from 'better-sqlite3';
 import { getDocsDbPath, hasEmbeddings } from './db.js';
 import { encodeText, similarity, bytesToPhases, DEFAULT_DIM } from './hrr.js';
 
@@ -24,7 +24,7 @@ export function searchDocs(opts = {}) {
     throw new Error(`Database not found: ${dbPath}. Run "jsn docs sync" first.`);
   }
 
-  const db = new DatabaseSync(dbPath, { readOnly: true });
+  const db = new Database(dbPath, { readonly: true });
   const limit = Math.min(parseInt(opts.limit, 10) || 20, 1000);
   const offset = parseInt(opts.offset, 10) || 0;
   const bundle = opts.bundle ? String(opts.bundle) : null;

package/src/commands/docs/serve.js

@@ -4,7 +4,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import http from 'node:http';
 import { URL } from 'node:url';
-import { DatabaseSync } from 'node:sqlite';
+import Database from 'better-sqlite3';
 import { getDocsDbPath, hasEmbeddings } from './db.js';
 import { encodeText, similarity, bytesToPhases, DEFAULT_DIM } from './hrr.js';
 
@@ -72,7 +72,7 @@ export function serveDocs(opts = {}) {
     throw new Error(`Database not found: ${dbPath}. Run "jsn docs sync" first.`);
   }
 
-  const db = new DatabaseSync(dbPath, { readOnly: true });
+  const db = new Database(dbPath, { readonly: true });
   const hasEmb = hasEmbeddings(db);
   const hrrDim = (() => {
     try {

package/src/commands/setup.js

@@ -1,10 +1,13 @@
-import readline from 'node:readline';
-import { getEffectiveInstance, normalizeInstanceURL, saveConfig, setProfile } from '../config.js';
+import { loginWizard } from './auth.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.
 export function setupCmd(wrap) {
   return {
     command: 'setup',
-    describe: 'Interactive first-time 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', {
@@ -13,87 +16,10 @@ export function setupCmd(wrap) {
           default: false,
         });
     },
-    handler: wrap(async (_argv, app) => {
-      const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-      const ask = (q) => new Promise((resolve) => rl.question(q, resolve));
-
-      console.log('Welcome to JSN - ServiceNow CLI');
-      console.log();
-
-      let instance = getEffectiveInstance(app.config);
-      if (!instance) {
-        instance = await ask('ServiceNow instance URL (e.g., dev12345.service-now.com): ');
-        instance = normalizeInstanceURL(instance);
-      }
-      console.log(`Instance: ${instance}`);
-
-      // Warn if another profile already uses this instance URL
-      const existing = Object.entries(app.config.profiles || {}).find(([, p]) => p.instance_url === instance);
-      if (existing) {
-        console.log(`Note: instance is also used by profile "${existing[0]}".`);
-      }
-
-      const profileName = (await ask('Profile name (default): ')) || 'default';
-      const profile = { instance_url: instance };
-      if (_argv['read-only']) {
-        profile.read_only = true;
-      }
-
-      const authMethod = await ask('Authentication method (OAuth/Basic) [OAuth]: ');
-      const useBasic = authMethod.toLowerCase().startsWith('b');
-
-      if (useBasic) {
-        const username = await ask('Username: ');
-        rl.close(); // Close outer readline before askHidden creates its own
-        const { loadCredentials, askHidden } = await import('../auth.js');
-        const existing = loadCredentials(instance) || loadCredentials(instance, username);
-        if (existing && existing.auth_method === 'basic') {
-          console.log(`Using existing credentials for ${instance}`);
-        } else {
-          const password = await askHidden('Password: ');
-          const { saveCredentials } = await import('../auth.js');
-          saveCredentials(instance, { auth_method: 'basic', username, password }, username);
-          profile.username = username;
-          console.log('Basic auth credentials saved');
-        }
-        profile.auth_method = 'basic';
-      } else {
-        profile.auth_method = 'oauth';
-      }
-
-      await setProfile(app.config, profileName, profile);
-      // Set as active profile so subsequent commands know which instance to use
-      app.config.activeProfile = profileName;
-      app.config.defaultProfile = profileName;
-      saveConfig(app.config);
-
-      if (!useBasic) {
-        const loginNow = await ask('Login now? [Y/n]: ');
-        if (!loginNow || loginNow.toLowerCase() !== 'n') {
-          await app.auth.login(instance);
-          // Re-save credentials under <user>@<instance> after verifying username
-          try {
-            const { SDKClient } = await import('./sdk.js');
-            const sdk = new SDKClient(instance, app.auth);
-            const user = await sdk.getCurrentUser();
-            if (user && user.user_name) {
-              const { loadCredentials, saveCredentials } = await import('../auth.js');
-              const stored = loadCredentials(instance);
-              if (stored && stored.access_token) {
-                stored.username = user.user_name;
-                saveCredentials(instance, stored, user.user_name);
-              }
-              profile.username = user.user_name;
-            }
-          } catch {
-            // Non-fatal — token saved, username will be set on next auth login
-          }
-          console.log('Login successful!');
-        }
-      }
-
-      rl.close();
-      app.ok({ setup: true, instance, profile: profileName }, { summary: 'Setup complete' });
+    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' });
     }),
   };
 }

package/src/commands/skill.js

@@ -39,7 +39,10 @@ function realHomeDir() {
  * profile directory, falling back to ~/.hermes/skills/ (legacy symlink path).
  */
 function hermesSkillDir() {
-  const base = path.join(realHomeDir(), '.hermes');
+  // JSN_HERMES_BASE_DIR lets tests point at a temp .hermes tree.
+  // realHomeDir() deliberately bypasses $HOME (Hermes overrides it to a
+  // sandbox dir), so tests can't control the base via HOME.
+  const base = process.env.JSN_HERMES_BASE_DIR || path.join(realHomeDir(), '.hermes');
   const profileEnv = process.env.HERMES_PROFILE;
   let profileName = profileEnv;
 

package/src/config.js

@@ -168,3 +168,12 @@ export function setProfile(cfg, name, profile) {
   cfg.profiles[name] = profile;
   return saveConfig(cfg);
 }
+
+export function setActiveProfile(cfg, name) {
+  if (!cfg.profiles || !cfg.profiles[name]) {
+    throw new Error(`Profile not found: ${name}`);
+  }
+  cfg.defaultProfile = name;
+  cfg.activeProfile = name;
+  return saveConfig(cfg);
+}

package/src/help.js

@@ -107,10 +107,8 @@ const DATA_COMMANDS = [
 ];
 
 const CONFIG_COMMANDS = [
-  { name: 'setup', desc: 'Interactive first-time setup' },
-  { name: 'auth', desc: 'OAuth authentication' },
-  { name: 'profiles', alias: 'profile', desc: 'Instance profiles' },
-  { name: 'updatesets', desc: 'Update sets (set, yolo, export, import)' },
+  { name: 'auth', desc: 'Authentication (login, status, switch, refresh, logout, remove)' },
+  { name: 'updatesets', desc: 'Update sets (set, create, export)' },
   { name: 'scopes', desc: 'Application scopes' },
 ];
 

package/src/mutations.js

@@ -2,6 +2,29 @@
 // Used by the read-only profile middleware to block mutation commands.
 // Each entry is a command path array matching argv._ tokens.
 
+// Dev commands that expose create/update/delete via buildDevCmd.
+// Each generates the root form (`jsn <name> create`) and the legacy dev form
+// (`jsn dev <name> create`), so read-only profiles block both spellings.
+const DEV_CRUD_COMMANDS = [
+  'actions', 'includes', 'rules', 'clientscripts', 'uiactions', 'uipolicies',
+  'tables', 'uipages', 'appmenu', 'acls', 'roles', 'properties', 'relationships',
+  'appmodules', 'listcontrols', 'views', 'privileges', 'uxscripts',
+  'catalogscripts', 'scriptactions', 'scheduledjobs', 'asyncrules', 'triggers',
+  'email', 'restmethods', 'restmessage', 'soapmessages', 'uimacros',
+  'cataloguipolicies', 'aliases', 'columns', 'flows', 'scrapi',
+];
+
+function devCrudPaths(name) {
+  return [
+    [name, 'create'],
+    [name, 'update'],
+    [name, 'delete'],
+    ['dev', name, 'create'],
+    ['dev', name, 'update'],
+    ['dev', name, 'delete'],
+  ];
+}
+
 export const MUTATION_COMMANDS = [
   // Incidents
   ['incidents', 'create'],
@@ -37,18 +60,20 @@ export const MUTATION_COMMANDS = [
   ['groups', 'delete'],
   // Catalog
   ['catalog', 'create-item'],
-  // Dev flows
-  ['dev', 'flows', 'create'],
-  ['dev', 'flows', 'update'],
-  ['dev', 'flows', 'delete'],
-  // Dev scopes
+  // Dev CRUD commands (root + `jsn dev` forms)
+  ...DEV_CRUD_COMMANDS.flatMap(devCrudPaths),
+  // Dev eval (no sub-action)
+  ['dev', 'eval'],
+  // Scopes: create + set (root + dev forms)
+  ['scopes', 'create'],
+  ['scopes', 'set'],
   ['dev', 'scopes', 'create'],
   ['dev', 'scopes', 'set'],
-  // Dev eval
-  ['dev', 'eval'],
-  // Dev updatesets
-  ['dev', 'updatesets', 'set'],
+  // Update sets: create + set (root + dev forms)
+  ['updatesets', 'create'],
+  ['updatesets', 'set'],
   ['dev', 'updatesets', 'create'],
+  ['dev', 'updatesets', 'set'],
 ];
 
 /**

package/src/commands/profiles.js

@@ -1,190 +0,0 @@
-import { normalizeInstanceURL, saveConfig, setProfile } from '../config.js';
-
-export function profilesCmd(wrap) {
-  return {
-    command: 'profiles [subcommand]',
-    aliases: ['profile'],
-    describe: 'Manage configuration profiles',
-    builder: (yargs) => {
-      return yargs
-        .command({
-          command: 'create <name>',
-          describe: 'Create a new profile',
-          builder: (sub) => sub
-            .positional('name', {
-              describe: 'Profile name',
-              type: 'string',
-            })
-            .option('instance', {
-              alias: 'i',
-              describe: 'ServiceNow instance URL (e.g. dev12345.service-now.com)',
-              type: 'string',
-            })
-            .option('username', {
-              alias: 'u',
-              describe: 'Username for basic auth',
-              type: 'string',
-            })
-            .option('password', {
-              alias: 'p',
-              describe: 'Password for basic auth',
-              type: 'string',
-            })
-            .option('read-only', {
-              describe: 'Mark profile as read-only (blocks mutation commands)',
-              type: 'boolean',
-              default: false,
-            }),
-          handler: wrap(async (argv, app) => {
-            const name = argv.name;
-            if (app.config.profiles && app.config.profiles[name]) {
-              throw new Error(`Profile "${name}" already exists. Use "jsn profiles update" or remove it first.`);
-            }
-
-            let instance = argv.instance;
-            if (!instance) {
-              throw new Error(`Instance URL is required.\n\n  jsn profiles create ${name} --instance https://dev12345.service-now.com`);
-            }
-            instance = normalizeInstanceURL(instance);
-
-            const profile = { instance_url: instance };
-
-            // If username/password provided, save credentials too
-            if (argv.username && argv.password) {
-              const { saveCredentials } = await import('../auth.js');
-              saveCredentials(instance, {
-                auth_method: 'basic',
-                username: argv.username,
-                password: argv.password,
-              }, argv.username);
-              profile.auth_method = 'basic';
-              profile.username = argv.username;
-            }
-
-            // If read-only flag is set, mark the profile
-            if (argv['read-only']) {
-              profile.read_only = true;
-            }
-
-            await setProfile(app.config, name, profile);
-
-            app.ok({
-              profile: name,
-              instance,
-              auth_method: profile.auth_method || 'oauth (not yet logged in)',
-            }, { summary: `Profile "${name}" created for ${instance}` });
-          }),
-        })
-        .command({
-          command: 'list',
-          describe: 'List all profiles',
-          handler: wrap(async (_argv, app) => {
-            const profiles = [];
-            for (const [name, profile] of Object.entries(app.config.profiles || {})) {
-              const instance = profile.instance_url || '';
-              const isAuth = app.auth.isAuthenticatedFor(instance);
-              const isDefault = name === app.config.defaultProfile;
-              profiles.push({
-                name,
-                instance,
-                username: profile.username || '',
-                authenticated: isAuth,
-                default: isDefault,
-                read_only: profile.read_only || false,
-              });
-            }
-
-            // Build context-aware breadcrumb: suggest switching to a non-active profile
-            const breadcrumbs = [];
-            if (profiles.length > 0) {
-              const activeName = app.config.activeProfile || app.config.defaultProfile;
-              const nonActiveProfiles = profiles.filter(p => p.name !== activeName);
-              if (nonActiveProfiles.length > 0) {
-                const suggestName = nonActiveProfiles[0].name;
-                breadcrumbs.push({
-                  action: 'switch',
-                  cmd: `jsn profiles use ${suggestName}`,
-                  description: 'Switch to a different profile',
-                });
-              }
-            }
-
-            app.ok({ profiles }, { summary: `${profiles.length} profile(s)`, breadcrumbs });
-          }),
-        })
-        .command({
-          command: 'use <name>',
-          describe: 'Set active profile',
-          handler: wrap(async (argv, app) => {
-            const name = argv.name;
-            if (!app.config.profiles[name]) {
-              throw new Error(`Profile not found: ${name}`);
-            }
-            app.config.defaultProfile = name;
-            app.config.activeProfile = name;
-            saveConfig(app.config);
-            app.ok({ active_profile: name }, { summary: `Active profile: ${name}` });
-          }),
-        })
-        .command({
-          command: 'show [name]',
-          describe: 'Show profile details',
-          handler: wrap(async (argv, app) => {
-            const name = argv.name || app.config.defaultProfile || Object.keys(app.config.profiles || {})[0];
-            if (!name || !app.config.profiles[name]) {
-              throw new Error('No profiles configured');
-            }
-            const profile = app.config.profiles[name];
-            const readOnlyNote = profile.read_only ? ' [READ-ONLY]' : '';
-            app.ok({ name, ...profile }, { summary: `Profile: ${name}${readOnlyNote}` });
-          }),
-        })
-        .command({
-          command: 'remove <name>',
-          describe: 'Remove a profile',
-          handler: wrap(async (argv, app) => {
-            const name = argv.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 clean up 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}` });
-          }),
-        })
-
-    },
-    handler: (argv) => {
-      // When no subcommand is given, show help
-      if (!argv._[1]) {
-        console.log('Manage your ServiceNow instance profiles.\n');
-        console.log('Usage: jsn profiles <create|list|show|use|remove> [options]\n');
-        console.log('Commands:');
-        console.log('  create <name>  Create a new profile (--instance required)');
-        console.log('  list           List all profiles');
-        console.log('  show [name]    Show profile details');
-        console.log('  use  <name>    Switch to a different profile');
-        console.log('  remove <name>  Remove a profile');
-        console.log('\nRun "jsn profiles <command> --help" for more details.');
-        console.log('\nNote: You can also create a profile by authenticating:');
-        console.log('  jsn auth login --profile <name> <instance-url>');
-        console.log('  jsn auth login --profile staging --password https://dev12345.service-now.com');
-      }
-    },
-  };
-}