@jacebenson/jsn 4.1.0 → 4.2.0

package/src/cli.js

@@ -5,17 +5,20 @@ import { hideBin } from 'yargs/helpers';
 import process from 'node:process';
 import path from 'node:path';
 import fs from 'node:fs';
-import { loadConfig, getActiveProfile, globalConfigDir } from './config.js';
+import { loadConfig, globalConfigDir } from './config.js';
 import { App } from './app.js';
+import { resolveSession, applySession } from './session.js';
 import { renderHelp } from './help.js';
-import { isMutationCommand } from './mutations.js';
-import { guardExit } from './errors.js';
-import { FormatJSON } from './output.js';
+import { isMutationCommand, refreshMutationCommands } from './mutations.js';
+import { noInstanceCommands, dailyCheckSkipCommands } from './capabilities.js';
+import { guardExit, exitWithError } from './errors.js';
 
 // Command modules
 import { setupCmd } from './commands/setup.js';
 import { authCmd } from './commands/auth.js';
 import { recordsCmd } from './commands/records.js';
+import { cmdbCmd } from './commands/cmdb.js';
+import { snippetsCmd } from './commands/snippets.js';
 import { catalogCmd } from './commands/catalog.js';
 import { incidentsCmd } from './commands/incidents.js';
 import { changesCmd } from './commands/changes.js';
@@ -26,6 +29,7 @@ import { groupsCmd } from './commands/groups.js';
 import { groupMembersCmd } from './commands/groupmembers.js';
 import { groupRolesCmd } from './commands/grouproles.js';
 import { ticketsCmd } from './commands/tickets.js';
+import { codesearchCmd } from './commands/codesearch.js';
 import { versionCmd } from './commands/version.js';
 import { devCmd } from './commands/dev.js';
 import { skillCmd, checkSkill } from './commands/skill.js';
@@ -35,7 +39,7 @@ import { docsCmd } from './commands/docs/docs.js';
 // Dev subcommands promoted to root level for progressive disclosure
 import {
   actionsCmd, includesCmd, rulesCmd,
-  clientScriptsCmd, uiActionsCmd, uiPoliciesCmd,
+  clientScriptsCmd, uiActionsCmd,
   tablesCmd, columnsCmd, importCmd,
   spPagesCmd, spWidgetsCmd, uiPagesCmd, appMenuCmd,
   aclsCmd, rolesCmd, propertiesCmd,
@@ -60,6 +64,8 @@ import { restCmd } from './commands/dev/rest.js';
 import { logsCmd } from './commands/dev/logs.js';
 import { scrapiCmd } from './commands/dev/scrapi.js';
 import { b4rulesCmd } from './commands/dev/b4rules.js';
+import { atfCmd } from './commands/atf.js';
+import { approvalsCmd } from './commands/approvals.js';
 
 function wrap(handler) {
   return async (argv) => {
@@ -71,37 +77,11 @@ function wrap(handler) {
       }
       await handler(argv, app);
     } catch (err) {
-      if (err.code === 'not_found') {
-        const id = argv._.slice(1).join(' ') || argv.id || argv.name || argv.sysID || '';
-        process.stderr.write(`Error (${err.code}): ${err.message}\n`);
-        if (id) {
-          process.stderr.write(`\nHint: The identifier "${id}" was not found. Check the name or sys_id.\n`);
-        }
-        process.exit(1);
-      }
-      if (err.code === 'usage') {
-        process.stderr.write(`Error (usage): ${err.message}\n`);
-        process.exit(2);
-      }
-      if (err.code === 'system_error') {
-        process.stderr.write(`Error (system): ${err.message}\n`);
-        process.exit(3);
-      }
-      if (err.code === 'confirmation_required') {
-        // Structured error for AI agents / piped consumers: emit the
-        // JSON envelope on stdout (where tooling reads) so the agent can
-        // surface the decision to its user or re-run with --force.
-        const app = argv.app;
-        if (app && app.output.effectiveFormat() === FormatJSON) {
-          app.err(err);
-        } else {
-          process.stderr.write(`Error: ${err.message}\n`);
-          if (err.hint) process.stderr.write(`\n${err.hint}\n`);
-        }
-        process.exit(1);
-      }
-      process.stderr.write(`Error: ${err.message}\n`);
-      process.exit(1);
+      // All error rendering goes through the unified renderer in
+      // src/errors.js — exit codes, stream choice, and the JSON envelope
+      // for confirmation_required live there, not here.
+      const identifier = argv._.slice(1).join(' ') || argv.id || argv.name || argv.sysID || '';
+      exitWithError(err, { app: argv.app, argv, identifier });
     }
   };
 }
@@ -109,15 +89,17 @@ function wrap(handler) {
 export function buildCLI() {
   const cfg = loadConfig();
   const app = new App(cfg);
+  // Root command names for the completion filter — captured from the yargs
+  // registry after the chain below finishes registering all commands.
+  let rootCommands = [];
 
-  return yargs(hideBin(process.argv))
+  const cliInstance = yargs(hideBin(process.argv))
     .scriptName('jsn')
     .usage('Usage: jsn <command> [options]')
     .middleware([
       // Attach App instance to every command
       (argv) => {
         argv.app = app;
-        argv._profile = cfg.profiles || {};
       },
     ])
     .options({
@@ -133,13 +115,21 @@ export function buildCLI() {
       },
       format: {
         type: 'string',
-        description: 'Output format: auto, json, markdown, styled, quiet',
-        choices: ['auto', 'json', 'markdown', 'styled', 'quiet'],
+        description: 'Output format: auto, json, markdown, styled, quiet, csv',
+        choices: ['auto', 'json', 'markdown', 'styled', 'quiet', 'csv'],
       },
       json: {
         type: 'boolean',
         description: 'Output in JSON format (shortcut for --format=json)',
       },
+      csv: {
+        type: 'boolean',
+        description: 'Output in CSV format (shortcut for --format=csv)',
+      },
+      get: {
+        type: 'string',
+        description: 'Extract a JSON path from the output envelope (e.g. --get "data.records.0.number"); no jq needed',
+      },
       quiet: {
         type: 'boolean',
         description: 'Output only data, no envelope (shortcut for --format=quiet)',
@@ -161,42 +151,37 @@ export function buildCLI() {
         if (argv.quiet) argv.format = 'quiet';
         if (argv.styled) argv.format = 'styled';
         if (argv.markdown) argv.format = 'markdown';
+        if (argv.csv) argv.format = 'csv';
         if (argv.format) {
           app.output.setFormat(argv.format);
         }
-        // --profile: resolve profile name to its instance URL
-        // --instance wins if both are specified (explicit URL > profile reference)
-        if (argv.profile) {
-          const profile = (cfg.profiles || {})[argv.profile];
-          if (!profile) {
-            guardExit(argv, {
-              code: 'unknown_profile',
-              message: `Unknown profile "${argv.profile}"`,
-              hint: 'Run "jsn auth status" to list profiles.',
-            });
-          }
-          const url = profile.instance_url;
-          app._overrideInstance = url;
-          argv._overrideInstance = url;
-          // Temporarily switch active profile so auth picks up the right user
-          cfg.activeProfile = argv.profile;
+        if (argv.get) {
+          app.output.setJqFilter(argv.get);
         }
-        if (argv.instance) {
-          app._overrideInstance = argv.instance;
-          argv._overrideInstance = argv.instance;
+      },
+      // --profile / --instance resolve through the SESSION (src/session.js).
+      // resolveSession is pure; applySession is the ONLY place cfg.activeProfile
+      // / app._overrideInstance change — no more argv._overrideInstance mirror
+      // or duplicated --instance branches across middlewares.
+      (argv) => {
+        const session = resolveSession(argv, cfg);
+        if (session.unknownProfile) {
+          guardExit(argv, {
+            code: 'unknown_profile',
+            message: `Unknown profile "${session.unknownProfile}"`,
+            hint: 'Run "jsn auth status" to list profiles.',
+          });
         }
+        applySession(app, session);
       },
       // Guard mutation commands: require an instance, block read-only profiles
       (argv) => {
         const cmd = (argv._[0] || '').toString();
-        if (!cmd || ['help', 'version', 'completion', 'setup', 'auth', 'skill', 'docs'].includes(cmd)) {
+        // Skip-list is derived from command capability declarations
+        // (noInstance: true), not a hand-maintained name list.
+        if (!cmd || noInstanceCommands().has(cmd)) {
           return;
         }
-        // Check for --instance override
-        if (argv.instance) {
-          app._overrideInstance = argv.instance;
-          argv._overrideInstance = argv.instance;
-        }
         if (isMutationCommand(argv)) {
           try {
             app.requireInstance();
@@ -206,12 +191,10 @@ export function buildCLI() {
             // raw stack trace).
             guardExit(argv, { code: err.code || 'usage', message: err.message, hint: err.hint });
           }
-          const profile = getActiveProfile(cfg);
-          if (profile?.read_only === true) {
-            const name = cfg.activeProfile || cfg.defaultProfile;
+          if (app.session?.readOnly === true) {
             guardExit(argv, {
               code: 'read_only',
-              message: `Profile "${name}" is read-only. Mutations are blocked.`,
+              message: `Profile "${app.session.profileName}" is read-only. Mutations are blocked.`,
               hint: 'Switch to a write-enabled profile first:\n  jsn auth switch <name>',
             });
           }
@@ -219,22 +202,22 @@ export function buildCLI() {
       },
     ])
     .middleware(async (argv) => {
-      // Override instance for this command run
-      if (argv._overrideInstance) {
-        app.setEffectiveInstance(argv._overrideInstance);
-      }
-
+      // Session (incl. --instance/--profile overrides) was already applied
+      // by the middleware above — nothing to re-apply here.
       const cmd = (argv._[0] || '').toString();
+      // Daily-check + context-header skip-list is derived from command
+      // capability declarations (skipDailyChecks: true).
+      const dailySkips = dailyCheckSkipCommands();
 
       // Daily npm version check (fire-and-forget, non-blocking)
       // Checks npm for newer jsn releases, at most once per 24 hours.
-      const skipNpmCheck = ['help', 'version', 'completion', 'skill', 'docs'].includes(cmd)
+      const skipNpmCheck = dailySkips.has(cmd)
         || process.env.JSN_NO_VERSION_CHECK === '1'
         || argv.json
         || argv.quiet;
 
       // Auto-check skill on every command (once per 24h, non-blocking)
-      const skipSkillCheck = ['help', 'version', 'completion', 'skill', 'docs'].includes(cmd)
+      const skipSkillCheck = dailySkips.has(cmd)
         || process.env.JSN_NO_SKILL_CHECK === '1'
         || argv['no-skill-check'];
       if (!skipSkillCheck) {
@@ -293,7 +276,7 @@ export function buildCLI() {
       }
 
       // Print context header for interactive terminals
-      if (!['help', 'version', 'completion', 'skill', 'docs'].includes(cmd)) {
+      if (!dailySkips.has(cmd)) {
         await argv.app.printContextHeader(argv);
       }
     })
@@ -340,11 +323,10 @@ export function buildCLI() {
     .command(formsCmd(wrap))
     .command(listsCmd(wrap))
     .command(clientScriptsCmd(wrap))
-    .command(uiPoliciesCmd(wrap))
+    .command(uipoliciesCmd(wrap))
     .command(uiActionsCmd(wrap))
     .command(viewsCmd(wrap))
     .command(catalogscriptsCmd(wrap))
-    .command(uipoliciesCmd(wrap))
     .command(cataloguipoliciesCmd(wrap))
     // USER EXPERIENCE — Core UI
     .command(uiPagesCmd(wrap))
@@ -370,9 +352,14 @@ export function buildCLI() {
     .command(logsCmd(wrap))
     .command(propertiesCmd(wrap))
     // DATA
+    .command(cmdbCmd(wrap))
     .command(recordsCmd(wrap))
+    .command(snippetsCmd(wrap))
     .command(ticketsCmd(wrap))
+    .command(codesearchCmd(wrap))
     // DEVELOPER
+    .command(atfCmd(wrap))
+    .command(approvalsCmd(wrap))
     .command(evalCmd(wrap))
     .command(restCmd(wrap))
     .command(skillCmd(wrap))
@@ -381,6 +368,59 @@ export function buildCLI() {
     // Legacy
     .command(devCmd(wrap))
     .demandCommand(1, 'You must specify a command')
+    // Completion plumbing under a hidden command name, so the explicit
+    // 'completion' command below owns the UX. (#176)
+    // The custom filter fixes two yargs behaviors:
+    // 1. Under strictCommands(), yargs' default completion handler aborts
+    //    when the current word isn't an exact command match. Delegating to
+    //    completionFilter (the default generator) sidesteps that.
+    // 2. When the current word is an exact ALIAS (e.g. "inc" for incidents),
+    //    yargs descends into that command's subcommands, so a still-being-
+    //    typed "jsn inc<TAB>" offers subcommands that can't match the prefix.
+    //    When completing the FIRST word (depth 1, the command slot), merge
+    //    in the root command list — the shell's compgen prefix-filters the
+    //    final list anyway.
+    .completion('__completion', false, (current, argv, completionFilter, done) => {
+      completionFilter((err, completions) => {
+        let out = completions || [];
+        const depth = (argv._ || []).length;
+        if (current && !current.startsWith('-') && depth <= 2) {
+          out = [...new Set([...out, ...rootCommands])];
+        }
+        done([...new Set(out)]);
+      });
+    })
+    // User-facing completion command with a real help page (install docs).
+    // yargs' built-in completion command prints the script even for --help,
+    // which is why the plumbing above uses the hidden '__completion' name.
+    .command({
+      command: 'completion',
+      describe: 'Generate shell completion script',
+      builder: (y) => y
+        .usage('Usage: jsn completion > <file for your shell>')
+        .epilogue([
+          'Install for your shell:',
+          '',
+          '  # bash (auto-loaded if the bash-completion package is installed)',
+          '  jsn completion > ~/.local/share/bash-completion/jsn',
+          '',
+          '  # bash (simple)',
+          '  jsn completion >> ~/.bashrc',
+          '',
+          '  # fish',
+          '  jsn completion > ~/.config/fish/completions/jsn.fish',
+          '',
+          '  # zsh — the generated script is bash-style, load via bashcompinit.',
+          '  # Add to ~/.zshrc:',
+          '  autoload -U +X bashcompinit && bashcompinit',
+          '  source <(jsn completion)',
+          '',
+          'Restart your shell (or source the file) after installing.',
+        ].join('\n')),
+      handler: () => {
+        cliInstance.showCompletionScript();
+      },
+    })
     .help('help', 'Show help')
     .version(false)
     .strictCommands()
@@ -410,6 +450,16 @@ export function buildCLI() {
       process.stderr.write(msg + '\n');
       process.exit(1);
     });
+
+  // Snapshot the root command names (plus aliases) for the completion
+  // filter. Done before any parse — command builders mutate the registry.
+  rootCommands = cliInstance.getInternalMethods().getCommandInstance().getCommands();
+
+  // The capability registry is fully populated now that every command
+  // factory has run — generate the mutation guard's path list.
+  refreshMutationCommands();
+
+  return cliInstance;
 }
 
 // Run if invoked directly (bin/jsn.js calls cli.parse())

package/src/commands/_ticket.js

@@ -1,11 +1,15 @@
 // Generic command builder for CRUD operations on a ServiceNow table
 // Used by incidents, changes, requests, tasks, and most dev subcommands
 
-import { getStringField, formatRecordForDisplay, buildQuerySuffix, resolveFieldsParam, confirmDelete, assertSafeExactMatch, canPrompt } from '../helpers.js';
-import { search } from '@inquirer/prompts';
+import { getStringField, formatRecordForDisplay, buildQuerySuffix, resolveFieldsParam, confirmDelete, interactiveList, canPrompt } from '../helpers.js';
+import { resolveRecord, resolveSysId } from '../resolve-record.js';
 import { FormatAuto } from '../output.js';
+import { declareCapabilities } from '../capabilities.js';
 
 export function buildTicketCommands(table, displayName, alias, defaultColumns, stateMap, iconFn, wrap) {
+  // Ticket-style CRUD: list/show are reads; create/update/delete mutate.
+  // Root-level only (no `jsn dev` spelling).
+  declareCapabilities(displayName, { mutationSubcommands: ['create', 'update', 'delete'] });
   return {
     command: `${displayName} [subcommand]`,
     aliases: [table, alias],
@@ -28,18 +32,22 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
             const offset = argv.offset;
 
             // Interactive picker in TTY with auto format and no explicit query/offset
-            const isInteractive = canPrompt();
-            if (isInteractive && app.output.getFormat() === FormatAuto && !query && offset === 0) {
+            if (canPrompt() && app.output.getFormat() === FormatAuto && !query && offset === 0) {
               const pickerColumns = ['sys_id', 'number', 'short_description', 'state', 'assigned_to'];
-              const pickerParams = new URLSearchParams();
-              pickerParams.set('sysparm_limit', String(limit));
-              pickerParams.set('sysparm_offset', '0');
-              pickerParams.set('sysparm_display_value', 'all');
-              pickerParams.set('sysparm_fields', pickerColumns.join(','));
-              pickerParams.set('sysparm_query', 'ORDERBYDESCsys_updated_on');
-
-              const pickerRecords = await app.sdk.list(table, pickerParams);
-              if (pickerRecords.length === 0) {
+              const picked = await interactiveList({
+                app, table, singular: displayName.slice(0, -1), columns: pickerColumns, limit,
+                labelField: 'number',
+                formatLabel: (r) => {
+                  let label = `${getStringField(r, 'number')} ${getStringField(r, 'short_description')} | ${getStringField(r, 'state')}`;
+                  const assigned = getStringField(r, 'assigned_to');
+                  if (assigned) label += ` → ${assigned}`;
+                  return label;
+                },
+                formatValue: (r) => r,
+              });
+              if (picked === undefined) return; // user cancelled
+              if (picked === null) {
+                // canPrompt() passed, so null means the table is empty.
                 app.ok({
                   table,
                   count: 0,
@@ -56,58 +64,19 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
                 return;
               }
 
-              const choices = pickerRecords.map((record) => {
-                const number = getStringField(record, 'number');
-                const desc = getStringField(record, 'short_description');
-                const state = getStringField(record, 'state');
-                const assigned = getStringField(record, 'assigned_to');
-                let label = `${number} ${desc} | ${state}`;
-                if (assigned) {
-                  label += ` → ${assigned}`;
-                }
-                return { name: label, value: number };
+              const record = picked;
+              const number = getStringField(record, 'number');
+              record._context = {
+                instance_url: app.getEffectiveInstance(),
+                table,
+              };
+              app.ok(record, {
+                summary: `${displayName.charAt(0).toUpperCase() + displayName.slice(1)} ${number}`,
+                breadcrumbs: [
+                  { action: 'update', cmd: `jsn ${alias} update ${number} --data '{...}'`, description: `Update this ${displayName}` },
+                  { action: 'list', cmd: `jsn ${alias} list`, description: `Back to all ${table}` },
+                ],
               });
-
-              let selectedNumber;
-              try {
-                selectedNumber = await search({
-                  message: `Select a ${displayName.slice(0, -1)}:`,
-                  source: async (input) => {
-                    if (!input) return choices;
-                    const term = input.toLowerCase();
-                    return choices.filter(c => c.name.toLowerCase().includes(term));
-                  },
-                });
-              } catch (err) {
-                if (err.name === 'ExitPromptError' || (err.message && err.message.includes('force closed'))) {
-                  return;
-                }
-                throw err;
-              }
-
-              if (selectedNumber) {
-                assertSafeExactMatch(selectedNumber);
-                const showParams = new URLSearchParams();
-                showParams.set('sysparm_query', `number=${selectedNumber}`);
-                showParams.set('sysparm_display_value', 'all');
-                showParams.set('sysparm_limit', '1');
-                const showRecords = await app.sdk.list(table, showParams);
-                if (showRecords.length === 0) {
-                  throw new Error(`${displayName} not found: ${selectedNumber}`);
-                }
-                const record = showRecords[0];
-                record._context = {
-                  instance_url: app.getEffectiveInstance(),
-                  table,
-                };
-                app.ok(record, {
-                  summary: `${displayName.charAt(0).toUpperCase() + displayName.slice(1)} ${selectedNumber}`,
-                  breadcrumbs: [
-                    { action: 'update', cmd: `jsn ${alias} update ${selectedNumber} --data '{...}'`, description: `Update this ${displayName}` },
-                    { action: 'list', cmd: `jsn ${alias} list`, description: `Back to all ${table}` },
-                  ],
-                });
-              }
               return;
             }
 
@@ -162,16 +131,7 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
           describe: `Show a specific ${displayName}`,
           handler: wrap(async (argv, app) => {
             const number = argv.number;
-            assertSafeExactMatch(number);
-            const params = new URLSearchParams();
-            params.set('sysparm_query', `number=${number}`);
-            params.set('sysparm_display_value', 'all');
-            params.set('sysparm_limit', '1');
-            const records = await app.sdk.list(table, params);
-            if (records.length === 0) {
-              throw new Error(`${displayName} not found: ${number}`);
-            }
-            const record = records[0];
+            const record = await resolveRecord(app.sdk, { table, identifier: number, matchField: 'number', resource: displayName });
             record._context = {
               instance_url: app.getEffectiveInstance(),
               table,
@@ -218,16 +178,8 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
             .option('data', { type: 'string', demandOption: true, describe: 'JSON data to update' }),
           handler: wrap(async (argv, app) => {
             const number = argv.number;
-            assertSafeExactMatch(number);
             const recordData = JSON.parse(argv.data);
-            const findParams = new URLSearchParams();
-            findParams.set('sysparm_query', `number=${number}`);
-            findParams.set('sysparm_limit', '1');
-            const records = await app.sdk.list(table, findParams);
-            if (records.length === 0) {
-              throw new Error(`${displayName} not found: ${number}`);
-            }
-            const sysID = getStringField(records[0], 'sys_id');
+            const sysID = await resolveSysId(app.sdk, { table, identifier: number, matchField: 'number', resource: displayName });
             const updated = await app.sdk.update(table, sysID, recordData);
             app.ok(updated, {
               summary: `Updated ${displayName} ${number}`,
@@ -244,15 +196,7 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
           handler: wrap(async (argv, app) => {
             const number = argv.number;
             await confirmDelete(app, argv, `Delete ${displayName} ${number}`);
-            assertSafeExactMatch(number);
-            const findParams = new URLSearchParams();
-            findParams.set('sysparm_query', `number=${number}`);
-            findParams.set('sysparm_limit', '1');
-            const records = await app.sdk.list(table, findParams);
-            if (records.length === 0) {
-              throw new Error(`${displayName} not found: ${number}`);
-            }
-            const sysID = getStringField(records[0], 'sys_id');
+            const sysID = await resolveSysId(app.sdk, { table, identifier: number, matchField: 'number', resource: displayName });
             await app.sdk.delete(table, sysID);
             app.ok({ number, message: `${displayName.charAt(0).toUpperCase() + displayName.slice(1)} deleted` }, {
               summary: `Deleted ${displayName} ${number}`,