@jacebenson/jsn 4.3.13-dev.76.1 → 4.3.13-dev.77.1

package/package.json

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

package/src/cli-adapter.js

@@ -116,6 +116,7 @@ export class LocalCLI {
 
   scriptName(value) { this.script = value; return this; }
   usage(value) { this.root.usageText = value; return this; }
+  epilogue(value) { this.root.epilogueText = value; return this; }
   middleware(fn) { this.middlewares.push(...(Array.isArray(fn) ? fn : [fn])); return this; }
   option(name, config) { this.root.options.set(name, { ...config, name }); return this; }
   options(config) { for (const [name, value] of Object.entries(config)) this.option(name, value); return this; }
@@ -294,6 +295,13 @@ export class LocalCLI {
         aliases: [...node.aliases],
         description: node.definition.describe || '',
         subcommands: node.children.filter(visible).map((child) => child.name),
+        discovery: node.definition.discovery || null,
+        help: `jsn ${node.name} --help`,
+        actions: node.children.filter(visible).map((child) => ({
+          name: child.name,
+          description: child.definition.describe || '',
+          help: `jsn ${node.name} ${child.name} --help`,
+        })),
       };
     };
     return {

package/src/cli.js

@@ -7,7 +7,7 @@ import fs from 'node:fs';
 import { loadConfig, globalConfigDir } from './config.js';
 import { App } from './app.js';
 import { resolveSession, applySession } from './session.js';
-import { renderHelp } from './help.js';
+import { renderHelp, renderTips } from './help.js';
 import { isMutationCommand, refreshMutationCommands } from './mutations.js';
 import { skippedUpdatesCmd } from './commands/skipped-updates.js';
 import { noInstanceCommands, dailyCheckSkipCommands, contextHeaderSkipCommands } from './capabilities.js';
@@ -15,6 +15,7 @@ import { guardExit, exitWithError, AppError, CodeUsage } from './errors.js';
 import { formatCommandList } from './helpers.js';
 
 // Command modules
+import { discoverCmd } from './commands/discover.js';
 import { setupCmd } from './commands/setup.js';
 import { authCmd } from './commands/auth.js';
 import { recordsCmd } from './commands/records.js';
@@ -419,6 +420,7 @@ export function buildCLI() {
     .command(skillCmd(wrap))
     .command(docsCmd(wrap))
     .command(versionCmd(wrap))
+    .command(discoverCmd(wrap, () => cliInstance.commandRegistry()))
     .demandCommand(1, 'You must specify a command')
     // Completion plumbing under a hidden command name, so the explicit
     // 'completion' command below owns the UX. (#176)
@@ -499,6 +501,7 @@ export function buildCLI() {
         }, { summary });
       })(argv);
     })
+    .epilogue(renderTips())
     .help('help', 'Show help')
     .version(false)
     .strictCommands()

package/src/commands/_generic.js

@@ -280,6 +280,13 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
     command: `${name} [subcommand]`,
     aliases: aliases || [],
     describe: `Manage ${name} (e.g. "${name} list --query nameLIKEincident")`,
+    discovery: {
+      table,
+      defaultColumns,
+      benefits: ['Configured list columns', 'Lookup by name or sys_id',
+        ...(showFields ? ['Configured show fields'] : []),
+        ...(opts.onShow ? ['Additional table-specific show processing'] : [])],
+    },
     builder,
     handler: (_argv) => {
       // This handler only runs when no subcommand is matched (the default case).

package/src/commands/_ticket.js

@@ -14,6 +14,7 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
     command: `${displayName} [subcommand]`,
     aliases: [table, alias],
     describe: `Manage ${displayName} (e.g. "${displayName} list --query priority=1")`,
+    discovery: { table, defaultColumns, benefits: ['Configured list columns', 'Ticket-specific create/update flags'] },
     builder: (yargs) => {
       return yargs
         .command({

package/src/commands/discover.js

@@ -0,0 +1,54 @@
+import { declareCapabilities } from '../capabilities.js';
+
+declareCapabilities('discover', { noInstance: true, skipDailyChecks: true });
+
+// The live registrations supply names, descriptions, aliases, actions, and
+// factory configuration. No separate inventory of table commands lives here.
+export function discoverCommands(registry, { query = '', table = '' } = {}) {
+  const words = query.toLowerCase().split(/\s+/).filter(Boolean);
+  return registry.commands.filter(command => {
+    const metadata = command.discovery;
+    if (table && metadata?.table !== table) return false;
+    const haystack = [command.name, ...command.aliases, command.description,
+      metadata?.table, ...(metadata?.benefits || []),
+      ...(command.actions || []).map(action => `${action.name} ${action.description}`)].join(' ').toLowerCase();
+    return words.every(word => haystack.includes(word));
+  });
+}
+
+export function discoverCmd(wrap, getRegistry) {
+  return {
+    command: 'discover [query]',
+    describe: 'Find commands by words in their names, aliases, descriptions, or configured table',
+    builder: y => y
+      .positional('query', { type: 'string', describe: 'Search words (quote multiple words)' })
+      .option('table', { type: 'string', describe: 'Find specialized commands configured for this exact table' })
+      .epilogue([
+        'Choose by intent:',
+        '  Cross-table tasks: jsn records list --table task --query "active=true" --json',
+        '  Custom tables: jsn records list --table x_example_record --limit 5 --json',
+        '  Table-specific defaults and views: jsn discover --table incident',
+        '  Rich request views (attachments and variables): jsn requests show --help',
+        '  Raw endpoints when needed: jsn rest --help',
+        'Generic records supports any accessible table; specialized commands provide configured defaults and table-specific behavior.',
+        'Discovery matches registered text; try fewer words if there are no matches.',
+        'Use --json for structured results or --json --get data.commands for only matches.',
+      ].join('\n')),
+    handler: wrap(async (argv, app) => {
+      const commands = discoverCommands(getRegistry(), { query: argv.query, table: argv.table });
+      const lines = commands.flatMap(command => [
+        `${command.name}: ${command.description}`,
+        ...(command.discovery ? [
+          `  Table: ${command.discovery.table}; default columns: ${command.discovery.defaultColumns.join(', ')}`,
+          ...command.discovery.benefits.map(benefit => `  ${benefit}`),
+        ] : []),
+        `  ${command.help}`,
+        ...(command.actions || []).map(action => `  ${action.help} — ${action.description}`),
+      ]);
+      if (!commands.length) lines.push('No registered matches. Try fewer words or use generic records for any accessible table: jsn records list --help');
+      app.ok({ commands, _formatted: lines.join('\n') }, {
+        summary: `${commands.length} matching command(s). Use jsn discover --help for guidance by intent.`,
+      });
+    }),
+  };
+}

package/src/help.js

@@ -200,14 +200,20 @@ function renderFlags(options) {
   return `\nFLAGS\n${lines.join('\n')}`;
 }
 
-function renderTips() {
+export function renderTips() {
   return `
 TIPS
-  --query is available on every list command (e.g. "incidents list --query priority=1")
+  Find commands by task words: "jsn discover catalog"; by configured table: "jsn discover --table incident"
+  Cross-table task searches and custom tables: "jsn records list --help"
+  Specialized commands offer configured columns, lookup, and table-specific views; inspect discovery results for details
+  Raw endpoints when needed: "jsn rest --help"; examples and intent guidance: "jsn discover --help"
   Use "jsn <command> --help" for details, or "jsn <command> list --help" for list options
   "jsn --json" prints the registered command surface as JSON for scripts and agents
 
 LEARN MORE
+  Some list commands offer a picker in an interactive terminal with automatic output.
+  Arrow keys browse (10 visible items); type to search; scroll to load more; Enter selects; Esc cancels.
+  Picker eligibility and search fields vary by command. Explicit output formats (including --json) skip pickers.
   Use "jsn <command> --help" for more information about a command.`;
 }