@jacebenson/jsn 2.0.2 → 2.1.0

package/package.json

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

package/src/auth.js

@@ -180,12 +180,33 @@ function loadCredentials(instance) {
 }
 
 function saveCredentials(instance, creds) {
+  // Stamp last_seen on every credential save
+  creds.last_seen = creds.last_seen || Math.floor(Date.now() / 1000);
   // Try keyring first, fall back to file
   if (!keyringStore(instance, creds)) {
     fs.writeFileSync(credentialsPath(instance), JSON.stringify(creds, null, 2), { mode: 0o600 });
   }
 }
 
+/**
+ * Get the last_seen timestamp for an instance, if available.
+ */
+function getLastSeen(instance) {
+  const creds = loadCredentials(instance);
+  if (!creds || !creds.last_seen) return null;
+  return creds.last_seen;
+}
+
+/**
+ * Update the last_seen timestamp for an instance to now.
+ */
+function touchLastSeen(instance) {
+  const creds = loadCredentials(instance);
+  if (!creds) return;
+  creds.last_seen = Math.floor(Date.now() / 1000);
+  saveCredentials(instance, creds);
+}
+
 function deleteCredentials(instance) {
   keyringDelete(instance);
   try {
@@ -250,6 +271,14 @@ export class AuthManager {
     this.httpClient = { timeout: 30000 };
   }
 
+  getLastSeen(instance) {
+    return getLastSeen(instance);
+  }
+
+  touchLastSeen(instance) {
+    return touchLastSeen(instance);
+  }
+
   isAuthenticated() {
     if (process.env.SERVICENOW_OAUTH_TOKEN) return true;
     if (getBasicAuthFromEnv()) return true;
@@ -515,3 +544,5 @@ export class AuthManager {
     deleteCredentials(instance);
   }
 }
+
+export { saveCredentials, loadCredentials, askHidden };

package/src/cli.js

@@ -6,6 +6,7 @@ import process from 'node:process';
 import { loadConfig, getEffectiveInstance } from './config.js';
 import { App } from './app.js';
 import { renderHelp } from './help.js';
+import { isMutationCommand } from './mutations.js';
 
 // Command modules
 import { setupCmd } from './commands/setup.js';
@@ -122,6 +123,24 @@ export const cli = yargs(hideBin(process.argv))
       }
     }
 
+    // Read-only profile check — block mutation commands on read-only profiles
+    const activeProfileName = cfg.activeProfile || cfg.defaultProfile;
+    if (activeProfileName && cfg.profiles[activeProfileName] && cfg.profiles[activeProfileName].read_only) {
+      const skipReadOnlyCheck = ['help', 'version', 'setup', 'auth', 'profiles', 'profile', 'skill', undefined].includes(cmd);
+      if (!skipReadOnlyCheck && isMutationCommand(argv)) {
+        process.stderr.write(`\n🔒 Profile "${activeProfileName}" is read-only.\n`);
+        process.stderr.write(`  Mutation commands are disabled on this profile.\n`);
+        const nonReadOnlyProfiles = Object.entries(cfg.profiles || {})
+          .filter(([n, p]) => n !== activeProfileName && !p.read_only)
+          .map(([n]) => n);
+        if (nonReadOnlyProfiles.length > 0) {
+          process.stderr.write(`  Switch to a writable profile:  jsn profiles use ${nonReadOnlyProfiles[0]}\n`);
+        }
+        process.stderr.write('\n');
+        process.exit(1);
+      }
+    }
+
     // Auto-check skill on every command (fire-and-forget, non-blocking)
     const skipSkillCheck = ['help', 'version', 'completion', 'skill'].includes(cmd)
       || process.env.JSN_NO_SKILL_CHECK === '1'

package/src/commands/auth.js

@@ -105,14 +105,28 @@ Find your instance URL in your browser's address bar when logged into ServiceNow
               // Non-fatal — token is saved, just couldn't verify
             }
 
-            // Save to profiles
-            const profileName = instanceURL.replace(/https?:\/\//, '').replace(/\.service-now\.com.*/, '').replace(/[^a-zA-Z0-9]/g, '-');
+            // Save to profiles — deduplicate by instance URL
             if (!app.config.profiles) {
               app.config.profiles = {};
             }
+
+            // Check if a profile already exists for this instance
+            let profileName = null;
+            for (const [existingName, existingProfile] of Object.entries(app.config.profiles)) {
+              if (existingProfile.instance_url === instanceURL) {
+                profileName = existingName;
+                break;
+              }
+            }
+
+            // If no existing profile found, generate a name from the URL
+            if (!profileName) {
+              profileName = instanceURL.replace(/https?:\/\//, '').replace(/\.service-now\.com.*/, '').replace(/[^a-zA-Z0-9]/g, '-');
+            }
+
             app.config.profiles[profileName] = {
               instance_url: instanceURL,
-              auth_method: 'oauth',
+              auth_method: argv.password ? 'basic' : 'oauth',
               username: username || undefined,
             };
 
@@ -130,11 +144,12 @@ Find your instance URL in your browser's address bar when logged into ServiceNow
               authenticated: true,
               instance: instanceURL,
               username: username || undefined,
+              profile: profileName,
               default: setDefault || undefined,
             };
             const summary = username
-              ? `✓ Authenticated to ${instanceURL} as ${username}`
-              : `✓ Authenticated to ${instanceURL}`;
+              ? `✓ Authenticated to ${instanceURL} as ${username} (profile: ${profileName})`
+              : `✓ Authenticated to ${instanceURL} (profile: ${profileName})`;
             app.ok(result, { summary });
           }),
         })
@@ -170,21 +185,54 @@ Examples:
 
             const profiles = [];
             for (const [name, profile] of Object.entries(app.config.profiles || {})) {
-              const isAuth = app.auth.isAuthenticatedFor(profile.instance_url);
+              const instance = profile.instance_url;
+              const isAuth = app.auth.isAuthenticatedFor(instance);
+              const lastSeen = app.auth.getLastSeen(instance);
+
+              // Try live verification
+              let verified = null;
+              let verifiedAt = null;
+              if (isAuth && instance) {
+                try {
+                  const { SDKClient } = await import('../sdk.js');
+                  const sdk = new SDKClient(instance, app.auth);
+                  const user = await sdk.getCurrentUser();
+                  if (user && user.user_name) {
+                    verified = true;
+                    verifiedAt = user.user_name;
+                  }
+                } catch {
+                  verified = false;
+                }
+              }
+
+              // Calculate days since last seen
+              let daysSinceLastSeen = null;
+              if (lastSeen) {
+                daysSinceLastSeen = Math.floor((Date.now() / 1000 - lastSeen) / 86400);
+              }
+
               profiles.push({
                 name,
-                instance: profile.instance_url,
+                instance,
                 authenticated: isAuth,
-                default: profile.instance_url === defaultInstance,
+                verified,
+                verified_as: verifiedAt || undefined,
+                last_seen: lastSeen || undefined,
+                days_since_last_seen: daysSinceLastSeen,
+                stale: daysSinceLastSeen > 7,
+                default: instance === defaultInstance,
               });
             }
 
-            app.ok({
+            const result = {
               default_instance: defaultInstance,
               authenticated: app.auth.isAuthenticated(),
               environment_auth: envToken ? true : undefined,
               profiles,
-            }, { summary: `${profiles.length} profile(s)` });
+            };
+
+            app.ok(result, { summary: `${profiles.length} profile(s)` });
           }),
         })
         .command({

package/src/commands/profiles.js

@@ -1,4 +1,4 @@
-import { saveConfig } from '../config.js';
+import { normalizeInstanceURL, saveConfig, setProfile } from '../config.js';
 
 export function profilesCmd(wrap) {
   return {
@@ -7,6 +7,74 @@ export function profilesCmd(wrap) {
     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,
+              });
+              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',
@@ -22,9 +90,26 @@ export function profilesCmd(wrap) {
                 username: profile.username || '',
                 authenticated: isAuth,
                 default: isDefault,
+                read_only: profile.read_only || false,
               });
             }
-            app.ok({ profiles }, { summary: `${profiles.length} profile(s)` });
+
+            // 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({
@@ -50,7 +135,8 @@ export function profilesCmd(wrap) {
               throw new Error('No profiles configured');
             }
             const profile = app.config.profiles[name];
-            app.ok({ name, ...profile }, { summary: `Profile: ${name}` });
+            const readOnlyNote = profile.read_only ? ' [READ-ONLY]' : '';
+            app.ok({ name, ...profile }, { summary: `Profile: ${name}${readOnlyNote}` });
           }),
         })
         .command({
@@ -78,8 +164,9 @@ export function profilesCmd(wrap) {
       // When no subcommand is given, show help
       if (!argv._[1]) {
         console.log('Manage your ServiceNow instance profiles.\n');
-        console.log('Usage: jsn profiles <list|show|use|remove> [options]\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');

package/src/commands/setup.js

@@ -1,10 +1,19 @@
 import readline from 'node:readline';
 import { getEffectiveInstance, normalizeInstanceURL, saveConfig, setProfile } from '../config.js';
+import { saveCredentials, loadCredentials, askHidden } from '../auth.js';
 
 export function setupCmd(wrap) {
   return {
     command: 'setup',
     describe: 'Interactive first-time setup',
+    builder: (yargs) => {
+      return yargs
+        .option('read-only', {
+          describe: 'Mark profile as read-only (blocks mutation commands)',
+          type: 'boolean',
+          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));
@@ -20,16 +29,43 @@ export function setupCmd(wrap) {
       console.log(`Instance: ${instance}`);
 
       const profileName = await ask('Profile name (default): ') || 'default';
-      await setProfile(app.config, profileName, { instance_url: instance });
+      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 existing = loadCredentials(instance);
+        if (existing && existing.auth_method === 'basic') {
+          console.log(`Using existing credentials for ${instance}`);
+        } else {
+          const username = await ask('Username: ');
+          rl.close(); // Close outer readline before askHidden creates its own
+          const password = await askHidden('Password: ');
+          saveCredentials(instance, { auth_method: 'basic', username, password });
+          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);
 
-      const loginNow = await ask('Login now? [Y/n]: ');
-      if (!loginNow || loginNow.toLowerCase() !== 'n') {
-        await app.auth.login(instance);
-        console.log('Login successful!');
+      if (!useBasic) {
+        const loginNow = await ask('Login now? [Y/n]: ');
+        if (!loginNow || loginNow.toLowerCase() !== 'n') {
+          await app.auth.login(instance);
+          console.log('Login successful!');
+        }
       }
 
       rl.close();

package/src/mutations.js

@@ -0,0 +1,52 @@
+// Centralized mutation command registry
+// Used by the read-only profile middleware to block mutation commands.
+// Each entry is a command path array matching argv._ tokens.
+
+export const MUTATION_COMMANDS = [
+  // Incidents
+  ['incidents', 'create'],
+  ['incidents', 'update'],
+  ['incidents', 'delete'],
+  // Changes
+  ['changes', 'create'],
+  ['changes', 'update'],
+  ['changes', 'delete'],
+  // Records
+  ['records', 'create'],
+  ['records', 'update'],
+  ['records', 'delete'],
+  // Requests
+  ['requests', 'create'],
+  ['requests', 'update'],
+  ['requests', 'delete'],
+  // Tasks
+  ['tasks', 'create'],
+  ['tasks', 'update'],
+  ['tasks', 'delete'],
+  // Dev
+  ['dev', 'eval'],
+  ['dev', 'updatesets', 'set'],
+  ['dev', 'updatesets', 'create'],
+  ['dev', 'scopes', 'set'],
+];
+
+/**
+ * Check if the parsed argv matches any mutation command pattern.
+ * @param {object} argv — yargs parsed argv with `_` array
+ * @returns {boolean}
+ */
+export function isMutationCommand(argv) {
+  const cmd = argv._ || [];
+  for (const pattern of MUTATION_COMMANDS) {
+    if (pattern.length !== cmd.length) continue;
+    let match = true;
+    for (let i = 0; i < pattern.length; i++) {
+      if (pattern[i] !== cmd[i]) {
+        match = false;
+        break;
+      }
+    }
+    if (match) return true;
+  }
+  return false;
+}

package/src/output.js

@@ -176,11 +176,31 @@ export class OutputWriter {
         this.writer.write('\n');
         for (const p of data.profiles) {
           const prefix = p.default ? '* ' : '  ';
-          const status = p.authenticated ? '✓' : '✗';
-          if (p.username) {
-            this.writer.write(`${prefix}${status} ${p.instance} (as ${p.username})\n`);
+          const authIcon = p.authenticated ? '✓' : '✗';
+
+          // Show verified status if we got one
+          let verifiedStr = '';
+          if (p.verified === true) {
+            verifiedStr = ' ✅';
+          } else if (p.verified === false) {
+            verifiedStr = ' ⚠️';
+          }
+
+          // Show stale hint if >7 days since last seen
+          let staleStr = '';
+          if (p.stale && p.days_since_last_seen) {
+            staleStr = ` (${p.days_since_last_seen}d ago — may have been released)`;
+          }
+
+          // Show lock icon for read-only profiles
+          const lockIcon = p.read_only ? ' 🔒' : '';
+
+          if (p.name) {
+            this.writer.write(`${prefix}${authIcon} ${p.name} — ${p.instance}${lockIcon}${verifiedStr}${staleStr}\n`);
+          } else if (p.username) {
+            this.writer.write(`${prefix}${authIcon} ${p.instance} (as ${p.username})${lockIcon}${verifiedStr}${staleStr}\n`);
           } else {
-            this.writer.write(`${prefix}${status} ${p.instance}\n`);
+            this.writer.write(`${prefix}${authIcon} ${p.instance}${lockIcon}${verifiedStr}${staleStr}\n`);
           }
         }
       }

package/src/sdk.js

@@ -65,6 +65,13 @@ export class SDKClient {
         return null;
       }
 
+      // Stamp last_seen on successful API call
+      try {
+        if (this.authProvider && typeof this.authProvider.touchLastSeen === 'function') {
+          this.authProvider.touchLastSeen(this.baseURL);
+        }
+      } catch { /* non-fatal */ }
+
       return JSON.parse(body);
     } catch (err) {
       if (err.name === 'AbortError') {