@jacebenson/jsn 3.0.6 → 3.1.0

package/src/commands/dev/scrapi.js

@@ -1,7 +1,7 @@
 // Custom scraPI command: list/show individual operations + one-shot API definition creation
 //
 // The 'create' subcommand lets you build a full Scripted REST API in one call:
-//   jsn dev scrapi create \
+//   jsn scrapi create \
 //     --name "SL Managed Services" --service-id managed_services --namespace slapi \
 //     --resource create=POST:/create:./create.js \
 //     --resource comment=POST:/comment:./comment.js
@@ -74,7 +74,7 @@ export function scrapiCmd(wrap) {
           builder: (y) => y
             .option('query', { type: 'string', describe: 'Encoded query (e.g. "nameLIKEincident")' })
             .option('columns', { alias: ['c', 'fields'], type: 'string', describe: 'Comma-separated columns' })
-            .option('limit', { alias: 'l', type: 'number', default: 20, describe: 'Max records' }),
+            .option('limit', { alias: 'l', type: 'number', default: 50, describe: 'Max records' }),
           handler: wrap(async (argv, app) => {
             const columns = argv.columns ? argv.columns.split(',') : ['name', 'sys_ws_definition', 'http_method', 'relative_path', 'sys_scope'];
             const query = argv.query || '';
@@ -97,8 +97,8 @@ export function scrapiCmd(wrap) {
             }, {
               summary: `${records.length} operation(s)`,
               breadcrumbs: [
-                { action: 'create', cmd: 'jsn dev scrapi create --name "My API" --service-id my-api --namespace myapp --resource get=GET:/items:./script.js', description: 'Create a new REST API' },
-                { action: 'show', cmd: 'jsn dev scrapi show <name>', description: 'Show operation details' },
+                { action: 'create', cmd: 'jsn scrapi create --name "My API" --service-id my-api --namespace myapp --resource get=GET:/items:./script.js', description: 'Create a new REST API' },
+                { action: 'show', cmd: 'jsn scrapi show <name>', description: 'Show operation details' },
               ],
             });
           }),
@@ -128,7 +128,7 @@ export function scrapiCmd(wrap) {
               return app.ok(records[0], {
                 summary: `Operation: ${getStringField(records[0], 'name') || id}`,
                 breadcrumbs: [
-                  { action: 'list', cmd: 'jsn dev scrapi list', description: 'Back to all operations' },
+                  { action: 'list', cmd: 'jsn scrapi list', description: 'Back to all operations' },
                 ],
               });
             }
@@ -182,7 +182,7 @@ export function scrapiCmd(wrap) {
                 formatted += `    ${(method + '  ').slice(0, 7)} ${relPath.padEnd(30)} ${opName}${active !== 'true' ? ' (inactive)' : ''}\n`;
               }
             } else {
-              formatted += `\n  (no resources — run jsn dev scrapi create --resource ... to add some)\n`;
+              formatted += `\n  (no resources — run jsn scrapi create --resource ... to add some)\n`;
             }
 
             app.ok({
@@ -207,8 +207,8 @@ export function scrapiCmd(wrap) {
             }, {
               summary: `API: ${defName} — ${childOps.length} resource(s)`,
               breadcrumbs: [
-                { action: 'create', cmd: 'jsn dev scrapi create --name "..." --service-id ... --namespace ... --resource ...', description: 'Create a new API' },
-                { action: 'list', cmd: 'jsn dev scrapi list', description: 'Back to all operations' },
+                { action: 'create', cmd: 'jsn scrapi create --name "..." --service-id ... --namespace ... --resource ...', description: 'Create a new API' },
+                { action: 'list', cmd: 'jsn scrapi list', description: 'Back to all operations' },
               ],
             });
           }),
@@ -316,8 +316,8 @@ export function scrapiCmd(wrap) {
               summary: `Created API "${apiName}" with ${operations.length} operation(s)`,
               notice: `View API: ${apiURL}`,
               breadcrumbs: [
-                { action: 'show', cmd: `jsn dev scrapi list --query "web_service_definition=${defSysId}"`, description: 'List operations for this API' },
-                { action: 'add', cmd: `jsn dev scrapi add-resource --api "${serviceId}" --name <name>=METHOD:/path:./script.js`, description: 'Add another resource' },
+                { action: 'show', cmd: `jsn scrapi list --query "web_service_definition=${defSysId}"`, description: 'List operations for this API' },
+                { action: 'add', cmd: `jsn scrapi add-resource --api "${serviceId}" --name <name>=METHOD:/path:./script.js`, description: 'Add another resource' },
               ],
             });
           }),
@@ -333,9 +333,9 @@ export function scrapiCmd(wrap) {
       console.log('  create      Create a new API with operations (one-shot)');
       console.log('');
       console.log('Examples:');
-      console.log('  jsn dev scrapi list');
-      console.log('  jsn dev scrapi show my_operation');
-      console.log('  jsn dev scrapi create \\');
+      console.log('  jsn scrapi list');
+      console.log('  jsn scrapi show my_operation');
+      console.log('  jsn scrapi create \\');
       console.log('    --name "My API" --service-id my-api --namespace myapp \\');
       console.log('    --resource "create=POST:/create:./create.js" \\');
       console.log('    --resource "list=GET:/list:./list.js"');

package/src/commands/dev/updatesets.js

@@ -15,7 +15,7 @@ export function updateSetsCmd(wrap) {
           builder: (y) => y
             .option('query', { type: 'string', describe: 'Encoded query (e.g. "nameLIKEincident" or "active=true")' })
             .option('columns', { alias: ['c', 'fields'], type: 'string', describe: 'Comma-separated columns (e.g. "number,short_description")' })
-            .option('limit', { alias: 'l', type: 'number', default: 20, describe: 'Max records' }),
+            .option('limit', { alias: 'l', type: 'number', default: 50, describe: 'Max records' }),
           handler: wrap(async (argv, app) => {
             const columns = argv.columns ? argv.columns.split(',') : ['name', 'state', 'application'];
             const query = argv.query || '';
@@ -24,6 +24,7 @@ export function updateSetsCmd(wrap) {
               app, table: 'sys_update_set', singular: 'update set', columns, limit: argv.limit, query, labelField: 'name',
               formatLabel: r => `${getStringField(r, 'name')} [${getStringField(r, 'state') || '?'}]`,
             });
+            if (picked === undefined) return; // user cancelled
             if (picked) {
               picked._context = { instance_url: app.getEffectiveInstance(), table: 'sys_update_set' };
               return app.ok(picked, { summary: `Update set: ${getStringField(picked, 'name')}` });
@@ -151,12 +152,12 @@ export function updateSetsCmd(wrap) {
               breadcrumbs: [
                 {
                   action: 'set',
-                  cmd: `jsn dev updatesets set "${argv.name}"`,
+                  cmd: `jsn updatesets set "${argv.name}"`,
                   description: 'Switch to this update set',
                 },
                 {
                   action: 'complete',
-                  cmd: `jsn dev updatesets complete "${argv.name}"`,
+                  cmd: `jsn updatesets complete "${argv.name}"`,
                   description: 'Mark as complete when done',
                 },
               ],
@@ -225,9 +226,9 @@ export function updateSetsCmd(wrap) {
         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 dev updatesets <command> --help" for details.');
+        console.log('\nRun "jsn updatesets <command> --help" for details.');
         console.log('\nTip: Create an update set first:');
-        console.log('  jsn dev updatesets create --name "My Feature"');
+        console.log('  jsn updatesets create --name "My Feature"');
         console.log('  # → Auto-set as current, then record changes are captured.');
       }
     },

package/src/commands/records.js

@@ -74,7 +74,7 @@ export function recordsCmd(wrap) {
             const breadcrumbs = [
               { action: 'create', cmd: `jsn records create --table ${table} --data '{...}'`, description: 'Create a new record' },
               { action: 'filter', cmd: `jsn records list --table ${table} --query "priority=1"`, description: 'Filter: priority 1 only' },
-              { action: 'columns', cmd: `jsn dev columns --table ${table}`, description: 'View available columns' },
+              { action: 'columns', cmd: `jsn columns --table ${table}`, description: 'View available columns' },
             ];
             if (argv['sys-id']) {
               breadcrumbs.unshift({
@@ -188,12 +188,12 @@ export function recordsCmd(wrap) {
             const breadcrumbs = [
               ...result.flows.map(f => ({
                 action: 'show',
-                cmd: `jsn dev flows show "${f.flow}"`,
+                cmd: `jsn flows show "${f.flow}"`,
                 description: `View flow details for ${f.flow}`,
               })),
               ...result.businessRules.slice(0, 5).map(br => ({
                 action: 'show',
-                cmd: `jsn dev rules show "${br.name}"`,
+                cmd: `jsn rules show "${br.name}"`,
                 description: `View business rule: ${br.name}`,
               })),
             ];

package/src/help.js

@@ -9,23 +9,63 @@ const COMMAND_GROUPS = {
     { name: 'tasks', alias: 'task', desc: 'Manage catalog tasks' },
     { name: 'tickets', alias: 'ticket', desc: 'Query generic tickets' },
   ],
-  'DATA & ADMIN': [
+  'AUTOMATION': [
+    { name: 'flows', desc: 'Manage Flow Designer flows' },
+    { name: 'actions', alias: 'action', desc: 'Manage flow actions (sys_hub_action_type_definition)' },
+    { name: 'rules', alias: 'br', desc: 'Manage business rules' },
+    { name: 'scrapi', desc: 'Manage Scripted REST APIs' },
+    { name: 'updatesets', desc: 'Manage update sets (set, yolo, export, import)' },
+    { name: 'eval', desc: 'Run server-side JavaScript' },
+    { name: 'rest', desc: 'Make raw REST API calls' },
+  ],
+  'ACCESS': [
+    { name: 'acls', alias: 'acl', desc: 'Manage access controls' },
+    { name: 'roles', alias: 'role', desc: 'Manage roles' },
+    { name: 'scopes', desc: 'Manage application scopes' },
+    { name: 'properties', alias: 'prop', desc: 'Manage system properties' },
+    { name: 'privileges', alias: 'priv', desc: 'Manage scope privileges' },
+    { name: 'securitytypes', alias: 'st', desc: 'Manage security types' },
+    { name: 'aliases', alias: 'als', desc: 'Manage table aliases' },
+  ],
+  'USER EXPERIENCE': [
+    { name: 'forms', desc: 'Manage form layouts' },
+    { name: 'lists', desc: 'Manage list layouts' },
+    { name: 'clientscripts', alias: 'cs', desc: 'Manage client scripts' },
+    { name: 'uipolicies', alias: 'up', desc: 'Manage UI policies' },
+    { name: 'uiactions', alias: 'ua', desc: 'Manage UI actions' },
+    { name: 'sppages', desc: 'Manage Service Portal pages' },
+    { name: 'spwidgets', desc: 'Manage Service Portal widgets' },
+    { name: 'uipages', desc: 'Manage UI pages' },
+    { name: 'appmenu', desc: 'Manage application menus' },
+    { name: 'listcontrols', alias: 'lc', desc: 'Manage list controls' },
+    { name: 'views', alias: 'vw', desc: 'Manage views' },
+    { name: 'uxscripts', alias: 'ux', desc: 'Manage UX source scripts' },
+    { name: 'catalogscripts', desc: 'Manage catalog client scripts' },
+    { name: 'cataloguipolicies', alias: 'cup', desc: 'Manage catalog UI policies' },
+  ],
+  'DATA': [
     { name: 'records', desc: 'Generic Table API for any table' },
+    { name: 'tables', alias: 't', desc: 'Manage table definitions (sys_db_object)' },
+    { name: 'columns', alias: 'col', desc: 'Manage column definitions (sys_dictionary)' },
+    { name: 'includes', alias: 'si', desc: 'Manage script includes' },
+    { name: 'import', desc: 'Manage import sets' },
+    { name: 'logs', desc: 'View system logs' },
     { name: 'users', alias: 'user', desc: 'Manage ServiceNow users' },
     { name: 'groups', alias: 'group', desc: 'Manage groups' },
     { name: 'groupmembers', alias: 'gm', desc: 'Manage group memberships' },
     { name: 'grouproles', alias: 'gr', desc: 'Manage group roles' },
-  ],
-  'DEVELOPMENT': [
-    { name: 'dev', desc: 'Manage development artifacts (flows, includes, rules, ACLs, etc.)' },
-  ],
-  'CONFIGURATION': [
-    { name: 'setup', desc: 'Interactive first-time setup' },
-    { name: 'auth', desc: 'Manage OAuth authentication' },
-    { name: 'profiles', alias: 'profile', desc: 'Manage instance profiles' },
+    { name: 'relationships', alias: 'rel', desc: 'Manage table relationships' },
+    { name: 'appmodules', alias: 'am', desc: 'Manage application modules' },
   ],
 };
 
+const CONFIGURATION_COMMANDS = [
+  { name: 'setup', desc: 'Interactive first-time setup' },
+  { name: 'auth', desc: 'Manage OAuth authentication' },
+  { name: 'profiles', alias: 'profile', desc: 'Manage instance profiles' },
+  { name: 'dev', desc: '[DEPRECATED] All dev subcommands are now top-level — use jsn flows, jsn acls, etc.' },
+];
+
 const UTILITY_COMMANDS = [
   { name: 'skill', desc: 'Manage the jsn AI agent skill file (show, fetch, install)' },
   { name: 'version', desc: 'Show version information (--check for npm updates)' },
@@ -67,6 +107,7 @@ LEARN MORE
 
 export function renderHelp() {
   const sections = Object.entries(COMMAND_GROUPS).map(([name, cmds]) => renderGroup(name, cmds));
+  const configSection = renderGroup('CONFIGURATION', CONFIGURATION_COMMANDS);
   const utilitySection = renderGroup('UTILITY', UTILITY_COMMANDS);
 
   return [
@@ -76,6 +117,8 @@ export function renderHelp() {
     '',
     ...sections,
     '',
+    configSection,
+    '',
     utilitySection,
     '',
     renderFlags(),

package/src/helpers.js

@@ -1,7 +1,7 @@
 // Shared helper utilities
 
 import fs from 'node:fs';
-import search from '@inquirer/search';
+import { paginatedSearch } from './paginated-search.js';
 import { isTTY, FormatAuto } from './output.js';
 
 export function getStringField(record, field) {
@@ -89,53 +89,56 @@ export function resolveFieldsParam(columns) {
  * @param {string} opts.labelField — field used to match selection (default: 'name')
  * @returns {Promise<void>|null} null if no selection made or non-interactive
  */
-export async function interactiveList({ app, table, singular, columns, limit = 20, query = '', formatLabel, labelField = 'name' }) {
+export async function interactiveList({ app, table, singular, columns, limit = 50, query = '', formatLabel, labelField = 'name' }) {
+  app.requireInstance();
   const effectiveFormat = app.output.getFormat() === FormatAuto ? (isTTY(process.stdout) ? FormatAuto : FormatAuto) : app.output.getFormat();
   if (effectiveFormat !== FormatAuto || !isTTY(process.stdout) || !isTTY(process.stdin) || query) {
     return null; // not interactive — caller should fall back to text/table
   }
 
   const pickerColumns = ['sys_id', labelField, ...columns.filter(c => c !== labelField && c !== 'sys_id' && c !== '*')];
-  const params = new URLSearchParams();
-  params.set('sysparm_limit', String(limit));
-  params.set('sysparm_display_value', 'all');
   const pickerFields = pickerColumns.join(',');
-  if (pickerFields) params.set('sysparm_fields', pickerFields);
-  params.set('sysparm_query', 'ORDERBYDESCsys_updated_on');
-
-  const records = await app.sdk.list(table, params);
-  if (records.length === 0) return null;
-
-  const choices = records.map(r => ({
-    name: formatLabel ? formatLabel(r) : (getStringField(r, labelField) || getStringField(r, 'sys_id')),
-    value: r,
-  }));
 
+  // Get total count
+  let totalCount = 0;
   try {
-    const selected = await search({
-      message: `Select ${vowelArticle(singular)} ${singular}:`,
-      source: async (input) => {
-        if (!input) return choices;
-        const term = input.toLowerCase();
-        return choices.filter(c => c.name.toLowerCase().includes(term));
-      },
-    });
-    return selected; // the record object
-  } catch (err) {
-    if (err.name === 'ExitPromptError' || (err.message && err.message.includes('force closed'))) {
-      return null;
+    totalCount = await app.sdk.aggregateCount(table, '');
+  } catch {
+    totalCount = 0;
+  }
+  if (totalCount === 0) return null;
+
+  // Server source adapter for paginatedSearch: (term, offset) => choices[]
+  async function serverSource(term, offset) {
+    const params = new URLSearchParams();
+    params.set('sysparm_limit', String(limit));
+    params.set('sysparm_display_value', 'all');
+    if (pickerFields) params.set('sysparm_fields', pickerFields);
+    if (term) {
+      params.set('sysparm_query', `${labelField}LIKE${term}^ORDERBYDESCsys_updated_on`);
+    } else {
+      params.set('sysparm_query', 'ORDERBYDESCsys_updated_on');
+      params.set('sysparm_offset', String(offset));
     }
-    throw err;
+    const records = await app.sdk.list(table, params);
+    return records.map(r => ({
+      name: formatLabel ? formatLabel(r) : (getStringField(r, labelField) || getStringField(r, 'sys_id')),
+      value: r,
+    }));
   }
-}
 
-function vowelArticle(word) {
-  const first = word.charAt(0).toLowerCase();
-  return first === 'a' || first === 'e' || first === 'i' || first === 'o' || first === 'u' ? 'an' : 'a';
+  const selected = await paginatedSearch({
+    message: `Select ${singular === 'flow' ? 'a flow' : `a ${singular}`}`,
+    pageSize: 10,
+    totalCount,
+    source: serverSource,
+  });
+  // null = cancelled → undefined so callers skip fallback table
+  if (selected === null) return undefined;
+  return selected?.value; // unwrap {name, value} → raw record
 }
 
 /**
- * Known derived (read-only) ServiceNow fields that should not be set directly.
  * Maps table name → array of field names that are computed by the platform.
  * When a create/update payload contains these, a warning is emitted.
  */

package/src/paginated-search.js

@@ -0,0 +1,178 @@
+/**
+ * Paginated interactive search prompt with server-side pagination.
+ *
+ * Uses raw readline for terminal control — @inquirer/search doesn't support
+ * scroll-based pagination (source only fires on keystrokes, not on scroll).
+ *
+ * Returns the selected choice ({name, value}), or null on cancel.
+ */
+
+import readline from 'node:readline';
+
+export async function paginatedSearch({ message, pageSize, totalCount, pageSize: pgSize, source }) {
+  const PAGE = pageSize || pgSize || 10;
+  let choices = [];
+  let active = 0;
+  let loaded = 0;
+  let cancelled = false;
+  let term = '';
+  let outputLines = 0; // number of lines currently on screen
+
+  // Write + track: returns number of newlines written (cursor advance)
+  function writeLines(lines) {
+    const out = lines.join('\n');
+    process.stdout.write(out);
+    return lines.length - 1; // N elements = N-1 newlines = cursor advances this many
+  }
+
+  function render() {
+    if (outputLines > 0) {
+      process.stdout.moveCursor(0, -outputLines);
+      process.stdout.clearScreenDown();
+    } else {
+      // First render: ensure we start on a fresh line
+      process.stdout.cursorTo(0);
+      process.stdout.clearLine(0);
+    }
+
+    const buf = [];
+
+    // Header: show message + count
+    const countInfo = totalCount > 0 ? ` (${loaded} of ${totalCount} loaded)` : '';
+    buf.push(`${message}${countInfo}`);
+
+    // Visible window: center active item
+    const start = Math.max(0, active - Math.floor(PAGE / 2));
+    const end = Math.min(choices.length, start + PAGE);
+    const visible = choices.slice(start, end);
+
+    for (let i = 0; i < visible.length; i++) {
+      const choice = visible[i];
+      const isActive = (start + i) === active;
+      const prefix = isActive ? '\x1b[7m' : '';
+      const suffix = isActive ? '\x1b[0m' : '';
+      const display = choice.name.length > 70 ? choice.name.slice(0, 67) + '...' : choice.name;
+      buf.push(`  ${prefix}${display}${suffix}`);
+    }
+
+    // Pad to constant height
+    while (buf.length < PAGE + 2) {
+      buf.push('');
+    }
+
+    // Footer
+    const more = loaded < totalCount;
+    const footer = more
+      ? `↑↓ navigate • ⏎ select • esc cancel • type to filter • ↓ at end loads more`
+      : `↑↓ navigate • ⏎ select • esc cancel • type to filter`;
+    buf.push('');
+    buf.push(footer);
+
+    // Search bar
+    buf.push(`> ${term}`);
+
+    outputLines = writeLines(buf);
+  }
+
+  function cleanup() {
+    if (outputLines > 0) {
+      process.stdout.moveCursor(0, -outputLines);
+      process.stdout.clearScreenDown();
+      outputLines = 0;
+    }
+    // Ensure raw mode is off
+    try { process.stdin.setRawMode(false); } catch { /* ok */ }
+  }
+
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+      terminal: true,
+    });
+    try { process.stdin.setRawMode(true); } catch { /* non-TTY */ }
+
+    let inputBuf = '';
+
+    async function loadPage() {
+      if (loaded >= totalCount) return;
+      const newItems = await source('', loaded);
+      if (newItems.length > 0) {
+        choices = choices.concat(newItems);
+        loaded = Math.min(choices.length, totalCount);
+      }
+    }
+
+    // Initial load
+    (async () => {
+      const initial = await source('', 0);
+      if (cancelled) return;
+      choices = initial;
+      loaded = Math.min(choices.length, totalCount || Infinity);
+      active = 0;
+      render();
+    })();
+
+    rl.input.on('keypress', async (_str, key) => {
+      if (key.name === 'escape' || key.name === 'q' || (key.ctrl && key.name === 'c')) {
+        cancelled = true;
+        rl.close();
+        return;
+      }
+
+      if (key.name === 'return' || key.name === 'enter') {
+        if (choices.length > 0 && active >= 0 && active < choices.length) {
+          rl.close();
+          return;
+        }
+      }
+
+      if (key.name === 'up' && active > 0) {
+        active--;
+        render();
+        return;
+      }
+
+      if (key.name === 'down') {
+        if (active < choices.length - 1) {
+          active++;
+          render();
+        } else if (loaded < totalCount) {
+          await loadPage();
+          if (active < choices.length - 1) active++;
+          render();
+        }
+        return;
+      }
+
+      if (key.name === 'backspace') {
+        if (inputBuf.length > 0) inputBuf = inputBuf.slice(0, -1);
+      } else if (key.sequence && key.sequence.length === 1 && !key.meta && !key.ctrl) {
+        inputBuf += key.sequence;
+      } else {
+        return;
+      }
+
+      // Search
+      term = inputBuf;
+      if (term) {
+        const results = await source(term, 0);
+        choices = results;
+        loaded = results.length;
+      } else {
+        // Reset to browse mode — reload first page
+        const results = await source('', 0);
+        choices = results;
+        loaded = Math.min(results.length, totalCount || Infinity);
+      }
+      active = 0;
+      render();
+    });
+
+    rl.on('close', () => {
+      cleanup();
+      const choice = (!cancelled && active >= 0 && active < choices.length) ? choices[active] : null;
+      resolve(cancelled ? null : choice);
+    });
+  });
+}