@jacebenson/jsn 3.0.6 → 3.1.1

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/groupmembers.js

@@ -148,6 +148,15 @@ export function groupMembersCmd(wrap) {
           }),
         });
     },
-    handler: () => {},
+    handler: () => {
+      console.log('Manage group memberships in sys_user_grmember.');
+      console.log('');
+      console.log('Available subcommands:');
+      console.log('  list                  List group members');
+      console.log('  add                   Add a user to a group');
+      console.log('  remove                Remove a user from a group');
+      console.log('');
+      console.log('Run "jsn groupmembers <command> --help" for details.');
+    },
   };
 }

package/src/commands/grouproles.js

@@ -148,6 +148,15 @@ export function groupRolesCmd(wrap) {
           }),
         });
     },
-    handler: () => {},
+    handler: () => {
+      console.log('Manage group roles in sys_user_has_role.');
+      console.log('');
+      console.log('Available subcommands:');
+      console.log('  list                  List group roles');
+      console.log('  add                   Add a role to a group');
+      console.log('  remove                Remove a role from a group');
+      console.log('');
+      console.log('Run "jsn grouproles <command> --help" for details.');
+    },
   };
 }

package/src/commands/groups.js

@@ -137,6 +137,17 @@ export function groupsCmd(wrap) {
           }),
         });
     },
-    handler: () => {},
+    handler: () => {
+      console.log('Manage ServiceNow groups from the sys_user_group table.');
+      console.log('');
+      console.log('Available subcommands:');
+      console.log('  list                  List groups');
+      console.log('  show <name or sys_id>  Show a group');
+      console.log('  create                Create a new group');
+      console.log('  update <identifier>   Update a group');
+      console.log('  delete <identifier>   Delete a group');
+      console.log('');
+      console.log('Run "jsn groups <command> --help" for details.');
+    },
   };
 }

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}`,
               })),
             ];
@@ -205,6 +205,18 @@ export function recordsCmd(wrap) {
         })
 
     },
-    handler: () => {},
+    handler: () => {
+      console.log('Query and manage records in any ServiceNow table.');
+      console.log('');
+      console.log('Available subcommands:');
+      console.log('  list                  List records from a table');
+      console.log('  get                   Get a single record by sys_id');
+      console.log('  create                Create a record');
+      console.log('  update                Update a record');
+      console.log('  delete                Delete a record');
+      console.log('  inspect               Inspect table schema and statistics');
+      console.log('');
+      console.log('Run "jsn records <command> --help" for details.');
+    },
   };
 }

package/src/commands/skill.js

@@ -230,6 +230,16 @@ export function skillCmd(wrap) {
           }),
         });
     },
-    handler: () => {},
+    handler: () => {
+      console.log('Manage the jsn AI agent skill file.');
+      console.log('');
+      console.log('Available subcommands:');
+      console.log('  show       Show the bundled skill file');
+      console.log('  fetch      Download the latest skill from GitHub');
+      console.log('  path       Show skill file locations');
+      console.log('  install    Install skill file to agents directory');
+      console.log('');
+      console.log('Run "jsn skill <command> --help" for details.');
+    },
   };
 }

package/src/commands/tickets.js

@@ -117,6 +117,17 @@ export function ticketsCmd(wrap) {
         })
 
     },
-    handler: () => {},
+    handler: () => {
+      console.log('Query generic tickets from the ticket table.');
+      console.log('');
+      console.log('Available subcommands:');
+      console.log('  list                  List tickets');
+      console.log('  show <number or sys_id>  Show a ticket');
+      console.log('  create                Create a new ticket');
+      console.log('  update <identifier>   Update a ticket');
+      console.log('  delete <identifier>   Delete a ticket');
+      console.log('');
+      console.log('Run "jsn tickets <command> --help" for details.');
+    },
   };
 }

package/src/commands/users.js

@@ -140,6 +140,17 @@ export function usersCmd(wrap) {
           }),
         });
     },
-    handler: () => {},
+    handler: () => {
+      console.log('Manage ServiceNow users from the sys_user table.');
+      console.log('');
+      console.log('Available subcommands:');
+      console.log('  list                  List users');
+      console.log('  show <name or sys_id>  Show a user by user_name or sys_id');
+      console.log('  create                Create a new user');
+      console.log('  update <identifier>   Update a user');
+      console.log('  delete <identifier>   Delete a user');
+      console.log('');
+      console.log('Run "jsn users <command> --help" for details.');
+    },
   };
 }

package/src/help.js

@@ -1,47 +1,140 @@
 // Custom grouped help renderer
-// Mirrors the Go version's custom Cobra help template
-
-const COMMAND_GROUPS = {
-  'CORE COMMANDS': [
-    { name: 'incidents', alias: 'inc', desc: 'Manage incidents' },
-    { name: 'changes', alias: 'chg', desc: 'Manage change requests' },
-    { name: 'requests', alias: 'req', desc: 'Manage service catalog requests' },
-    { name: 'tasks', alias: 'task', desc: 'Manage catalog tasks' },
-    { name: 'tickets', alias: 'ticket', desc: 'Query generic tickets' },
-  ],
-  'DATA & ADMIN': [
-    { name: 'records', desc: 'Generic Table API for any table' },
-    { 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' },
-  ],
-};
-
-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)' },
-];
+// Organized by ServiceNow domain model with subgroup dividers
 
 function renderGroup(name, commands) {
   const lines = [`\n${name}`];
   lines.push('─'.repeat(50));
   for (const cmd of commands) {
+    if (cmd.divider) {
+      lines.push('');
+      lines.push(`  ${cmd.divider}`);
+      continue;
+    }
     const aliasPart = cmd.alias ? ` (${cmd.alias})` : '';
     const padded = `  jsn ${cmd.name}`.padEnd(22);
-    lines.push(`${padded}${cmd.desc}${aliasPart}`);
+    const status = cmd.status ? ` ${cmd.status}` : '';
+    lines.push(`${padded}${cmd.desc}${aliasPart}${status}`);
   }
   return lines.join('\n');
 }
 
+const CORE_COMMANDS = [
+  { name: 'incidents', alias: 'inc', desc: 'Manage incidents' },
+  { name: 'changes', alias: 'chg', desc: 'Manage change requests' },
+  { name: 'requests', alias: 'req', desc: 'Manage service catalog requests' },
+  { name: 'tasks', alias: 'task', desc: 'Manage catalog tasks' },
+];
+
+const AUTOMATION_COMMANDS = [
+  { divider: '── Async ──' },
+  { name: 'flows', alias: 'flow', desc: 'Flow Designer flows' },
+  { name: 'actions', alias: 'action', desc: 'Flow action definitions' },
+  { name: 'scriptactions', desc: 'Script actions' },
+  { name: 'scheduledjobs', desc: 'Scheduled jobs' },
+  { name: 'triggers', desc: 'Event triggers' },
+  { name: 'asyncrules', desc: 'Asynchronous business rules' },
+
+  { divider: '── In Memory ──' },
+  { name: 'rules', alias: 'br', desc: 'Business rules (create, update, delete)' },
+  { name: 'workflows', desc: 'Workflow definitions' },
+  { name: 'decisiontables', desc: 'Decision tables' },
+  { name: 'assignments', desc: 'Assignment rules' },
+
+  { divider: '── Inbound ──' },
+  { name: 'scrapi', desc: 'Scripted REST APIs' },
+  { name: 'email', desc: 'Inbound email actions' },
+
+  { divider: '── Outbound ──' },
+  { name: 'restmessage', alias: 'rm', desc: 'REST Messages (sys_rest_message)' },
+  { name: 'restmethods', desc: 'REST Message methods (sys_rest_message_fn)' },
+  { name: 'soapmessages', desc: 'SOAP Messages' },
+  { name: 'soapfunctions', desc: 'SOAP Message functions' },
+];
+
+const ACCESS_COMMANDS = [
+  { name: 'acls', alias: 'acl', desc: 'Access controls' },
+  { name: 'b4rules', alias: 'b4r', desc: 'Before-query business rules (see also Automation)' },
+  { name: 'roles', alias: 'role', desc: 'Roles' },
+  { name: 'privileges', alias: 'priv', desc: 'Scope privileges' },
+  { name: 'securitytypes', alias: 'st', desc: 'Custom security types' },
+  { name: 'aliases', alias: 'als', desc: 'Connection & credential aliases' },
+  { name: 'groups', alias: 'group', desc: 'Manage groups' },
+  { name: 'groupmembers', alias: 'gm', desc: 'Group memberships' },
+  { name: 'grouproles', alias: 'gr', desc: 'Group roles' },
+  { name: 'users', alias: 'user', desc: 'Manage users' },
+];
+
+const UX_COMMANDS = [
+  { divider: '── Shared (across all experiences) ──' },
+  { name: 'forms', desc: 'Form layouts' },
+  { name: 'lists', desc: 'List layouts' },
+  { name: 'clientscripts', alias: 'cs', desc: 'Client scripts' },
+  { name: 'uipolicies', alias: 'up', desc: 'UI policies' },
+  { name: 'uiactions', alias: 'ua', desc: 'UI actions (buttons, links, context menus)' },
+  { name: 'views', alias: 'vw', desc: 'Views' },
+  { name: 'catalogitems', alias: 'ci', desc: 'Service Catalog items + variables' },
+  { name: 'catalogscripts', desc: 'Catalog client scripts' },
+  { name: 'cataloguipolicies', alias: 'cup', desc: 'Catalog UI policies' },
+
+  { divider: '── Core UI ──' },
+  { name: 'uipages', desc: 'UI pages' },
+  { name: 'uimacros', desc: 'UI macros' },
+  { name: 'listcontrols', alias: 'lc', desc: 'List controls' },
+
+  { divider: '── Service Portal ──' },
+  { name: 'sppages', desc: 'Service Portal pages' },
+  { name: 'spwidgets', desc: 'Service Portal widgets' },
+
+  { divider: '── Next Experience (Workspaces) ──' },
+  { name: 'uxscripts', alias: 'ux', desc: 'UX source scripts' },
+  { name: 'uxlists', desc: 'Workspace lists (sys_ux_list)' },
+  { name: 'uxapplicability', desc: 'Workspace applicability (m2m)' },
+
+  { divider: '── Navigation ──' },
+  { name: 'appmenu', desc: 'Application menus' },
+  { name: 'appmodules', alias: 'am', desc: 'Application modules' },
+];
+
+const DATA_COMMANDS = [
+  { divider: '── DB Schema ──' },
+  { name: 'tables', alias: 't', desc: 'Table definitions' },
+  { name: 'columns', alias: 'col', desc: 'Column definitions' },
+  { name: 'relationships', alias: 'rel', desc: 'Table relationships' },
+
+  { divider: '── Shared Code, Transforms, Logs ──' },
+  { name: 'includes', alias: 'si', desc: 'Script includes' },
+  { name: 'import', desc: 'Import sets' },
+  { name: 'logs', desc: 'System logs' },
+  { name: 'properties', alias: 'prop', desc: 'System properties' },
+
+  { name: 'records', desc: 'Generic Table API (any table)' },
+];
+
+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: 'scopes', desc: 'Application scopes' },
+];
+
+const DEVELOPER_COMMANDS = [
+  { name: 'eval', desc: 'Run server-side JavaScript' },
+  { name: 'rest', desc: 'Raw REST API calls' },
+  { name: 'skill', desc: 'AI agent skill file (show, fetch, install)' },
+  { name: 'version', desc: 'Version info (--check for npm updates)' },
+];
+
+const COMMAND_GROUPS = {
+  'CORE': CORE_COMMANDS,
+  'AUTOMATION': AUTOMATION_COMMANDS,
+  'ACCESS': ACCESS_COMMANDS,
+  'USER EXPERIENCE': UX_COMMANDS,
+  'DATA': DATA_COMMANDS,
+  'CONFIGURATION': CONFIG_COMMANDS,
+  'DEVELOPER': DEVELOPER_COMMANDS,
+};
+
 function renderFlags() {
   return `
 FLAGS
@@ -67,7 +160,6 @@ LEARN MORE
 
 export function renderHelp() {
   const sections = Object.entries(COMMAND_GROUPS).map(([name, cmds]) => renderGroup(name, cmds));
-  const utilitySection = renderGroup('UTILITY', UTILITY_COMMANDS);
 
   return [
     'Usage: jsn <command> [options]',
@@ -76,8 +168,6 @@ export function renderHelp() {
     '',
     ...sections,
     '',
-    utilitySection,
-    '',
     renderFlags(),
     renderTips(),
     '',

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,69 @@ 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' }) {
+function vowelArticle(word) {
+  const first = word.charAt(0).toLowerCase();
+  return first === 'a' || first === 'e' || first === 'i' || first === 'o' || first === 'u' ? 'an' : 'a';
+}
+
+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) {
+  if (effectiveFormat !== FormatAuto || !isTTY(process.stdout) || !isTTY(process.stdin)) {
     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;
+
+  // Paginated source adapter: (term, offset, { signal }) => choices[]
+  async function serverSource(term, offset, { signal } = {}) {
+    try {
+      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));
+      }
+      const records = await app.sdk.list(table, params);
+      if (!Array.isArray(records)) {
+        console.error('SDK non-array:', typeof records);
+        return [];
+      }
+      return records.map(r => ({
+        name: formatLabel ? formatLabel(r) : (getStringField(r, labelField) || getStringField(r, 'sys_id')),
+        value: r,
+      }));
+    } catch (err) {
+      console.error('serverSource error:', err.message || err);
+      return [];
     }
-    throw err;
   }
-}
 
-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,
+  });
+
+  return selected?.value; // unwrap {name, value} → raw record, undefined on cancel
 }
 
 /**
- * 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.
  */