@jacebenson/jsn 0.1.2 → 0.2.0

package/package.json

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

package/src/app.js

@@ -118,6 +118,21 @@ export class App {
     const updateSetStr = `]8;;${updateSetLink}\x07${updateSet}]8;;\x07`;
 
     process.stderr.write(`${profileStr} ${userStr} ${scopeStr} ${updateSetStr}\n\n`);
+
+    // ⚠️  Warning if in the Default update set
+    if (updateSet && updateSet.toLowerCase().includes('default')) {
+      process.stderr.write(
+        '\x1b[33m' + // yellow
+        '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n' +
+        '  ⚠  You are in the Default update set!\n' +
+        '  Create a named update set to capture your changes:\n' +
+        '    jsn dev updatesets create --name "My Feature"\n' +
+        '    jsn dev updatesets set "My Feature"\n' +
+        '  (Run \x1b[1mjsn updatesets yolo\x1b[22m to silence this warning)\n' +
+        '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n' +
+        '\x1b[0m' // reset
+      );
+    }
   }
 
   ok(data, opts = {}) {

package/src/auth.js

@@ -44,6 +44,40 @@ function removePKCEState(instance) {
 const DEFAULT_OAUTH_CLIENT_ID = '543e5655f77746a28228c6009a599dfb';
 const REDIRECT_URI = '/sdk-oauth.do';
 
+// ─── Basic auth from environment variables ───
+// SN_USERNAME / SN_PASSWORD — global credentials
+// SN_<INSTANCE>_USERNAME / SN_<INSTANCE>_PASSWORD — instance-specific (e.g. SN_DEV328604_USERNAME)
+
+function envVarName(instance) {
+  // Normalize instance URL to an env-var-safe name
+  // e.g. https://dev328604.service-now.com → DEV328604
+  const host = instance.replace(/https?:\/\//, '').replace(/\/.*$/, '').replace(/\.service-now\.com.*/, '').replace(/[^a-zA-Z0-9]/g, '').toUpperCase();
+  return host;
+}
+
+function getBasicAuthFromEnv(instance) {
+  if (!instance) {
+    // Try global env vars
+    const username = process.env.SN_USERNAME;
+    const password = process.env.SN_PASSWORD;
+    if (username && password) return { auth_method: 'basic', username, password };
+    return null;
+  }
+
+  // Try instance-specific env vars first (e.g. SN_DEV328604_USERNAME)
+  const host = envVarName(instance);
+  const instanceUser = process.env[`SN_${host}_USERNAME`];
+  const instancePass = process.env[`SN_${host}_PASSWORD`];
+  if (instanceUser && instancePass) return { auth_method: 'basic', username: instanceUser, password: instancePass };
+
+  // Fall back to global env vars
+  const globalUser = process.env.SN_USERNAME;
+  const globalPass = process.env.SN_PASSWORD;
+  if (globalUser && globalPass) return { auth_method: 'basic', username: globalUser, password: globalPass };
+
+  return null;
+}
+
 // Keychain constants — same as Go version (internal/auth/store.go)
 const KEYRING_SERVICE = 'servicenow-cli';
 const KEYRING_ATTR_SERVICE = 'service';
@@ -218,6 +252,7 @@ export class AuthManager {
 
   isAuthenticated() {
     if (process.env.SERVICENOW_OAUTH_TOKEN) return true;
+    if (getBasicAuthFromEnv()) return true;
     const instance = this.configProvider.getEffectiveInstance();
     if (!instance) return false;
     try {
@@ -230,6 +265,7 @@ export class AuthManager {
 
   isAuthenticatedFor(instance) {
     if (!instance) return false;
+    if (getBasicAuthFromEnv(instance)) return true;
     const creds = loadCredentials(instance);
     if (!creds) return false;
     if (creds.expires_at && Date.now() >= creds.expires_at * 1000) return false;
@@ -244,10 +280,16 @@ export class AuthManager {
     if (!instance) {
       throw errAuth('No instance configured');
     }
+    // Check basic auth from env vars first
+    const basicCreds = getBasicAuthFromEnv(instance);
+    if (basicCreds) return basicCreds;
     return this.getCredentialsFor(instance);
   }
 
   getCredentialsFor(instance) {
+    // Check basic auth from env vars first
+    const basicCreds = getBasicAuthFromEnv(instance);
+    if (basicCreds) return basicCreds;
     const creds = loadCredentials(instance);
     if (!creds) {
       throw errAuth(`Not authenticated for ${instance}`);
@@ -314,13 +356,68 @@ export class AuthManager {
    * Build an OAuth authorization URL and persist PKCE state for later use.
    * After calling this, the user can visit the URL in a browser and then
    * call loginWithCode() with the resulting authorization code.
+   * If waitFile is provided, the method will read the code from that file
+   * (waits for file to appear, polling every 2 seconds, up to 5 minutes).
    */
-  buildAuthURL(instanceURL) {
+  buildAuthURL(instanceURL, waitFile) {
     instanceURL = normalizeInstanceURL(instanceURL);
     const clientID = getOAuthClientID();
     const pkce = generatePKCE();
     savePKCEState(instanceURL, pkce);
-    return buildAuthURL(instanceURL, clientID, pkce);
+    const url = buildAuthURL(instanceURL, clientID, pkce);
+    if (waitFile) {
+      console.log(url);
+      console.log();
+      console.log(`Waiting for authorization code in file: ${waitFile}`);
+      console.log('(polling every 2 seconds — write the code to the file to complete login)');
+      return this._waitForCodeFile(instanceURL, clientID, pkce, waitFile);
+    }
+    return url;
+  }
+
+  async _waitForCodeFile(instanceURL, clientID, pkce, filePath, timeout = 300000) {
+    const start = Date.now();
+    const pollInterval = 2000;
+    while (Date.now() - start < timeout) {
+      try {
+        const code = fs.readFileSync(filePath, 'utf-8').trim();
+        if (code) {
+          console.log(`\nAuthorization code found in ${filePath}`);
+          removePKCEState(instanceURL);
+          const newCreds = await this.exchangeCode(instanceURL, clientID, code, pkce);
+          saveCredentials(instanceURL, newCreds);
+          console.log('Token exchange successful!\n');
+          return newCreds;
+        }
+      } catch {
+        // File not ready yet
+      }
+      await new Promise(r => setTimeout(r, pollInterval));
+    }
+    throw errAuth(`Timed out waiting for authorization code in ${filePath} (${timeout / 1000}s)`);
+  }
+
+  /**
+   * Authenticate with basic auth via environment variables.
+   * Reads SN_USERNAME/SN_PASSWORD (or SN_<INSTANCE>_USERNAME/SN_<INSTANCE>_PASSWORD).
+   * Stores the basic auth credentials so they persist across sessions.
+   */
+  async loginWithPassword(instanceURL) {
+    instanceURL = normalizeInstanceURL(instanceURL);
+    const creds = getBasicAuthFromEnv(instanceURL);
+    if (!creds) {
+      throw errAuth(
+        `No basic auth credentials found in environment.\n\n` +
+        `Set the following environment variables:\n` +
+        `  SN_USERNAME=admin           (or SN_${envVarName(instanceURL)}_USERNAME)\n` +
+        `  SN_PASSWORD=<password>      (or SN_${envVarName(instanceURL)}_PASSWORD)\n\n` +
+        `Then run:\n` +
+        `  jsn auth login --password ${instanceURL}`
+      );
+    }
+    saveCredentials(instanceURL, creds);
+    console.log(`✓ Basic auth credentials saved for ${instanceURL}`);
+    return creds;
   }
 
   /**

package/src/cli.js

@@ -12,6 +12,7 @@ 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';
 import { changesCmd } from './commands/changes.js';
 import { requestsCmd } from './commands/requests.js';
@@ -125,6 +126,7 @@ export const cli = yargs(hideBin(process.argv))
   .command(authCmd(wrap))
   .command(profilesCmd(wrap))
   .command(recordsCmd(wrap))
+  .command(catalogCmd(wrap))
   .command(incidentsCmd(wrap))
   .command(changesCmd(wrap))
   .command(requestsCmd(wrap))

package/src/commands/auth.js

@@ -5,7 +5,7 @@ import process from 'node:process';
 export function authCmd(wrap) {
   return {
     command: 'auth <subcommand>',
-    describe: 'Manage OAuth authentication',
+    describe: 'Manage authentication (OAuth or basic auth via env vars)',
     builder: (yargs) => {
       return yargs
         .command({
@@ -16,9 +16,17 @@ export function authCmd(wrap) {
               describe: 'Authorization code from browser (bypasses interactive prompt)',
               type: 'string',
             })
+            .option('password', {
+              describe: 'Authenticate with basic auth via env vars (SN_USERNAME/SN_PASSWORD)',
+              type: 'boolean',
+            })
             .option('print-url', {
               describe: 'Print the OAuth URL and exit (saves PKCE state for --code)',
               type: 'boolean',
+            })
+            .option('wait-file', {
+              describe: 'File path to watch for authorization code (used with --print-url)',
+              type: 'string',
             }),
           handler: wrap(async (argv, app) => {
             let instanceURL;
@@ -55,22 +63,29 @@ export function authCmd(wrap) {
 Examples:
   jsn auth login https://dev12345.service-now.com
   jsn auth login dev373698
-  jsn auth login https://acme.service-now.com
+  jsn auth login --password https://dev328604.service-now.com
 
 Find your instance URL in your browser's address bar when logged into ServiceNow.`);
                 }
               }
             }
 
+            // --password: authenticate with basic auth from env vars
+            if (argv.password) {
+              await app.auth.loginWithPassword(instanceURL);
+            }
+            // --print-url with --wait-file: print URL and wait for code file
+            else if (argv.printUrl && argv.waitFile) {
+              await app.auth.buildAuthURL(instanceURL, argv.waitFile);
+            }
             // --print-url: just print the URL and exit
-            if (argv.printUrl) {
+            else if (argv.printUrl) {
               const authURL = app.auth.buildAuthURL(instanceURL);
               console.log(authURL);
               return;
             }
-
             // --code: exchange the provided authorization code directly
-            if (argv.code) {
+            else if (argv.code) {
               await app.auth.loginWithCode(instanceURL, argv.code);
             } else {
               // Interactive: full OAuth flow with browser + prompt

package/src/commands/catalog.js

@@ -0,0 +1,157 @@
+// Catalog item management commands
+// NOTE: This is an AI-friendly high-level command that wraps sc_cat_item + item_option_new
+
+import { resolveItemOptionType } from '../helpers.js';
+
+export function catalogCmd(wrap) {
+  return {
+    command: 'catalog <subcommand>',
+    aliases: ['cat'],
+    describe: 'Manage Service Catalog items and variables',
+    builder: (yargs) => {
+      return yargs
+        .command({
+          command: 'create-item',
+          describe: 'Create a catalog item (sc_cat_item) with variables',
+          builder: (y) => y
+            .option('name', { alias: 'n', type: 'string', demandOption: true, describe: 'Catalog item name' })
+            .option('short-description', { alias: 'd', type: 'string', describe: 'Short description' })
+            .option('description', { type: 'string', describe: 'Full description' })
+            .option('category', { alias: 'c', type: 'string', describe: 'Category name (created if missing)' })
+            .option('variable', { alias: 'v', type: 'array', describe: 'Variable definition in format "name:type:label" or "name:type" (e.g. "reason:multilinetext:Reason" or "start_date:date")' })
+            .option('update-set', { type: 'string', describe: 'Update set sys_id or name to capture changes' }),
+          handler: wrap(async (argv, app) => {
+            const name = argv.name;
+            const shortDesc = argv['short-description'] || '';
+            const description = argv.description || shortDesc;
+            let categoryID = '';
+
+            // Resolve or create category
+            if (argv.category) {
+              const catParams = new URLSearchParams();
+              catParams.set('sysparm_query', `title=${argv.category}`);
+              catParams.set('sysparm_limit', '1');
+              catParams.set('sysparm_fields', 'sys_id,title');
+              const cats = await app.sdk.list('sc_category', catParams);
+              if (cats.length > 0) {
+                categoryID = cats[0].sys_id?.value || cats[0].sys_id;
+              } else {
+                const newCat = await app.sdk.create('sc_category', {
+                  title: argv.category,
+                  description: `Category for ${argv.category}`,
+                });
+                categoryID = newCat.sys_id?.value || newCat.sys_id;
+              }
+            }
+
+            // Create the catalog item
+            const item = await app.sdk.create('sc_cat_item', {
+              name,
+              short_description: shortDesc,
+              description,
+              category: categoryID || undefined,
+              active: true,
+              type: 'item',
+              stage: 'requested',
+            });
+            const itemID = item.sys_id?.value || item.sys_id;
+
+            // Parse and create variables
+            const varDefs = [];
+            if (argv.variable) {
+              for (const v of argv.variable) {
+                // Parse "label:type" or "name:type" or "name:type:label" etc.
+                const parts = String(v).split(':');
+                if (parts.length >= 2) {
+                  const typeName = parts.length >= 2 ? parts[parts.length - 2] : '';
+                  const label = parts.length >= 3 ? parts[parts.length - 1] : parts[0];
+                  const typeID = resolveItemOptionType(typeName);
+                  const sysName = parts[0].replace(/[^a-zA-Z0-9_]/g, '_').toLowerCase();
+                  varDefs.push({
+                    name: sysName,
+                    question_text: label,
+                    type: typeID,
+                    order: varDefs.length * 100 + 100,
+                    cat_item: itemID,
+                    mandatory: true,
+                    active: true,
+                  });
+                }
+              }
+
+              for (const vd of varDefs) {
+                try {
+                  await app.sdk.create('item_option_new', vd);
+                } catch {
+                  // variable creation failure is non-fatal
+                }
+              }
+            }
+
+            app.ok({
+              sys_id: itemID,
+              name,
+              category: argv.category || null,
+              variables_created: varDefs.length,
+              update_set: argv['update-set'] || null,
+              instance_url: app.getEffectiveInstance(),
+            }, {
+              summary: `Created catalog item: ${name} (${varDefs.length} variable(s))`,
+              breadcrumbs: [
+                { action: 'view', cmd: `jsn records get --table sc_cat_item --sys-id ${itemID}`, description: 'View the catalog item' },
+                { action: 'edit', cmd: `jsn catalog update-item ${itemID} --name "${name}"`, description: 'Edit the catalog item' },
+              ],
+            });
+          }),
+        })
+        .command({
+          command: 'list-items',
+          aliases: ['ls'],
+          describe: 'List catalog items',
+          builder: (y) => y
+            .option('limit', { alias: 'l', type: 'number', default: 20, describe: 'Max records' })
+            .option('category', { type: 'string', describe: 'Filter by category' }),
+          handler: wrap(async (argv, app) => {
+            let query = 'ORDERBYname';
+            if (argv.category) query = `category.titleLIKE${argv.category}^${query}`;
+            const params = new URLSearchParams();
+            params.set('sysparm_query', query);
+            params.set('sysparm_limit', String(argv.limit));
+            params.set('sysparm_display_value', 'all');
+            params.set('sysparm_fields', 'sys_id,name,short_description,category,active');
+            const items = await app.sdk.list('sc_cat_item', params);
+            app.ok({
+              table: 'sc_cat_item',
+              count: items.length,
+              columns: ['name', 'short_description', 'category', 'active'],
+              records: items.map(r => ({
+                sys_id: r.sys_id?.value || r.sys_id,
+                name: r.name?.display_value || r.name,
+                short_description: r.short_description?.display_value || r.short_description || '',
+                category: r.category?.display_value || '',
+                active: r.active?.display_value || r.active,
+              })),
+              context: { instance_url: app.getEffectiveInstance() },
+            }, { summary: `${items.length} catalog item(s)` });
+          }),
+        });
+    },
+    handler: (argv) => {
+      if (!argv._[1]) {
+        console.log('Manage Service Catalog items.\n');
+        console.log('Commands:');
+        console.log('  create-item    Create a catalog item (fast scaffold)');
+        console.log('  list-items     List catalog items');
+        console.log('\nExamples:');
+        console.log('  jsn catalog create-item "Request PTO" \\');
+        console.log('    --category "Time Off" \\');
+        console.log('    --short-description "Submit a PTO request" \\');
+        console.log('    --variable "start_date:date:Start Date" \\');
+        console.log('    --variable "type:select:Type" \\');
+        console.log('    --variable "reason:multilinetext:Reason/Notes"');
+        console.log('\nVariable types: string, multilinetext, select, date, datetime, reference, checkbox, email');
+        console.log('\nRun "jsn catalog <command> --help" for details.');
+      }
+    },
+  };
+}

package/src/commands/dev/updatesets.js

@@ -113,13 +113,52 @@ export function updateSetsCmd(wrap) {
               description: argv.description || argv.name,
               state: 'in progress',
             });
+
+            // Auto-set as current update set
+            const sysID = record?.sys_id?.value || record?.sys_id;
+            try {
+              const user = await app.sdk.list('sys_user', new URLSearchParams({
+                sysparm_query: 'user_name=javascript:gs.getUserName()',
+                sysparm_limit: '1',
+                sysparm_fields: 'sys_id',
+              }));
+              if (user.length > 0) {
+                const userSysID = user[0].sys_id?.value || user[0].sys_id;
+                // Check for existing preference
+                const prefParams = new URLSearchParams();
+                prefParams.set('sysparm_query', `user=${userSysID}^name=sys_update_set`);
+                prefParams.set('sysparm_limit', '1');
+                const prefs = await app.sdk.list('sys_user_preference', prefParams);
+                if (prefs.length > 0) {
+                  const prefID = prefs[0].sys_id?.value || prefs[0].sys_id;
+                  await app.sdk.update('sys_user_preference', prefID, { value: sysID });
+                } else {
+                  await app.sdk.create('sys_user_preference', {
+                    user: userSysID,
+                    name: 'sys_update_set',
+                    value: sysID,
+                    type: 'string',
+                  });
+                }
+              }
+            } catch {
+              // Non-fatal — auto-set is a convenience, not mandatory
+            }
+
             app.ok(record, {
               summary: `Created update set: ${argv.name}`,
-              breadcrumbs: [{
-                action: 'set',
-                cmd: `jsn dev updatesets set "${argv.name}"`,
-                description: 'Set as current update set',
-              }],
+              breadcrumbs: [
+                {
+                  action: 'set',
+                  cmd: `jsn dev updatesets set "${argv.name}"`,
+                  description: 'Switch to this update set',
+                },
+                {
+                  action: 'complete',
+                  cmd: `jsn dev updatesets complete "${argv.name}"`,
+                  description: 'Mark as complete when done',
+                },
+              ],
             });
           }),
         })
@@ -132,8 +171,13 @@ export function updateSetsCmd(wrap) {
         console.log('  list           List update sets');
         console.log('  show <name>    Show an update set');
         console.log('  set  <name>    Set the current update set');
-        console.log('  create         Create a new update set');
+        console.log('  create         Create a new update set (auto-sets as current)');
+        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 dev updatesets <command> --help" for details.');
+        console.log('\nTip: Create an update set first:');
+        console.log('  jsn dev updatesets create --name "My Feature"');
+        console.log('  # → Auto-set as current, then record changes are captured.');
       }
     },
   };

package/src/helpers.js

@@ -142,3 +142,41 @@ export function parseDataArg(argv) {
     throw new Error(`Invalid JSON: ${e.message}\n\nHint: On Windows PowerShell, use --data-file instead of --data to avoid quote mangling.\nRaw value: ${raw.substring(0, 200)}`, { cause: e });
   }
 }
+
+/**
+ * Translate human-readable type names to ServiceNow item_option_new type IDs.
+ * Maps common names like "date", "select", "multilinetext" to their integer IDs.
+ * Passes through numeric values unchanged.
+ */
+const ITEM_OPTION_TYPE_NAMES = {
+  '1': 1, 'yesno': 1, 'yes/no': 1, 'boolean': 1,
+  '2': 2, 'multilinetext': 2, 'textarea': 2, 'multiline': 2,
+  '3': 3, 'multiplechoice': 3,
+  '4': 4, 'numericscale': 4, 'rating': 4,
+  '5': 5, 'select': 5, 'dropdown': 5, 'choice': 5, 'selectbox': 5,
+  '6': 6, 'string': 6, 'text': 6, 'singlelinetext': 6,
+  '7': 7, 'checkbox': 7, 'check': 7,
+  '8': 8, 'reference': 8, 'lookup': 8,
+  '9': 9, 'date': 9,
+  '10': 10, 'datetime': 10, 'date/time': 10,
+  '11': 11, 'label': 11,
+  '14': 14, 'custom': 14,
+  '18': 18, 'lookupselect': 18, 'lookupselectbox': 18,
+  '20': 20, 'containerstart': 20,
+  '21': 21, 'listcollector': 21,
+  '23': 23, 'html': 23,
+  '26': 26, 'email': 26,
+  '29': 29, 'duration': 29,
+  '31': 31, 'requestedfor': 31,
+  '32': 32, 'richtextlabel': 32, 'richtext': 32,
+};
+
+export function resolveItemOptionType(type) {
+  if (type == null) return 6; // default: Single Line Text
+  if (typeof type === 'number') return type;
+  const lower = String(type).toLowerCase().replace(/[\s_-]/g, '');
+  if (ITEM_OPTION_TYPE_NAMES[lower] != null) return ITEM_OPTION_TYPE_NAMES[lower];
+  const asNum = parseInt(String(type), 10);
+  if (!isNaN(asNum) && asNum > 0 && asNum < 100) return asNum;
+  return 6; // fallback to Single Line Text
+}