@jacebenson/jsn 4.3.13-dev.101.1 → 4.3.13-dev.102.1

package/README.md

@@ -32,6 +32,17 @@ under npm's `dev` tag. Versions include the workflow run number and attempt
 The npm trusted publisher for `publish-dev.yml` must authorize the repository's
 `dev` GitHub environment, alongside the production publishing configuration.
 
+### Knowledge search
+
+Use `jsn knowledge search "VPN setup" --profile work` (alias `kb`) to search
+accessible articles, then `jsn knowledge show KB0000010 --profile work` to read
+one. Search supports bounded `--limit`/`--offset`, knowledge-base sys_ids with
+`--kb`, and `--language`. JSON preserves native HTML; human output uses Markdown.
+Hints preserve an explicitly selected profile/instance. The Knowledge API plugin
+(`sn_km_api`) must be available; access is evaluated by that API, with no fallback
+to direct table reads. Reads do not request view-count updates. See the
+[Knowledge API reference](https://www.servicenow.com/docs/r/yokohama/api-reference/rest-apis/knowledge-api.html).
+
 ### Instance Scan
 
 `jsn scan` manages checks and suites and runs scans against an explicit target.
@@ -132,3 +143,26 @@ This applies to root help, root JSON, `discover`, and root shell completion.
 Use `jsn --all-commands --help` or `jsn discover --all-commands --json` to inspect
 every registered command. Explicit command paths remain available and ServiceNow
 ACLs decide access. Reauthenticate (or refresh OAuth) after roles change.
+
+### Ordering catalog items
+
+Use `jsn catalogitems search "laptop" --profile work`, then
+`jsn catalogitems describe <item-sys-id> --profile work` to inspect pricing and
+variable definitions through the native Service Catalog API. Create a JSON file
+mapping variable names to values, then preview with
+`jsn catalogitems order <item-sys-id> --variables-file variables.json --dry-run --profile work`.
+Omit `--dry-run` to submit after confirmation. `--quantity` defaults to one;
+`--requested-for` accepts a user sys_id subject to instance delegation rules.
+
+Orders use `order_now`, preserving catalog fulfillment rather than inserting an
+RITM directly. The command handles standard catalog items; record producers and
+order guides require separate workflows. Server rules validate mandatory and
+dynamic variables at submission; a preview does not validate those rules. Preview
+output lists variable names, not entered values. This operation requires a
+write-enabled profile (also for previews), but no development update set.
+Confirmation follows the existing profile policy; automation can supply `--force`
+only for an approved order. Timeout or incomplete response is an uncertain
+outcome: inspect requests before retrying. JSN does not automatically submit a
+second order. `create/list/show` retain their definition-management behavior.
+
+See the [Service Catalog API reference](https://www.servicenow.com/docs/r/api-reference/rest-apis/c_ServiceCatalogAPI.html).

package/package.json

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

package/src/cli.js

@@ -22,6 +22,7 @@ import { authCmd } from './commands/auth.js';
 import { recordsCmd } from './commands/records.js';
 import { attachmentsCmd } from './commands/attachments.js';
 import { cmdbCmd } from './commands/cmdb.js';
+import { knowledgeCmd } from './commands/knowledge.js';
 import { snippetsCmd } from './commands/snippets.js';
 import { catalogCmd } from './commands/catalog.js';
 import { incidentsCmd } from './commands/incidents.js';
@@ -412,6 +413,7 @@ export function buildCLI() {
     .command(propertiesCmd(wrap))
     // DATA
     .command(cmdbCmd(wrap))
+    .command(knowledgeCmd(wrap))
     .command(recordsCmd(wrap))
     .command(attachmentsCmd(wrap))
     .command(transactionsCmd(wrap))

package/src/command-audience.js

@@ -2,8 +2,10 @@
 // Explicit command paths and --all-commands remain available to every account.
 const BASIC_COMMANDS = new Set([
   'incidents', 'changes', 'requests', 'tasks', 'tickets', 'approvals', 'records',
+  'knowledge',
   'groups', 'groupmembers', 'grouproles', 'users', 'setup', 'auth', 'skill',
   'version', 'docs', 'history', 'discover', 'completion',
+  'catalogitems',
 ]);
 
 export async function detectCommandAudience(sdk, username, instanceURL = sdk?.baseURL) {

package/src/commands/catalog-order.js

@@ -0,0 +1,93 @@
+import { parseDataArg, confirmDelete, quoteShellArg } from '../helpers.js';
+import { errAPI, errUsage } from '../errors.js';
+
+const ID = /^[a-f0-9]{32}$/i;
+const API = '/api/sn_sc/servicecatalog/items';
+const object = v => v && typeof v === 'object' && !Array.isArray(v);
+
+function emit(app, argv, data, summary, breadcrumbs = []) {
+  const connection = argv.profile ? ` --profile ${quoteShellArg(argv.profile)}` : argv.instance ? ` --instance ${quoteShellArg(argv.instance)}` : '';
+  app.ok(data, { summary, breadcrumbs: breadcrumbs.map(h => ({ ...h, cmd: h.cmd + connection })) });
+}
+function requireId(id) { if (!ID.test(id || '')) throw errUsage('Use the full catalog item sys_id; find it with catalogitems search.'); }
+async function describe(app, id) {
+  requireId(id);
+  const response = await app.sdk.request(`${app.sdk.baseURL}${API}/${id}`, { method: 'GET' });
+  if (!object(response?.result) || response.result.sys_id !== id) throw errAPI(200, 'Catalog API returned no readable item with the requested identity.');
+  return response.result;
+}
+function itemHints(id) {
+  return [{ action: 'describe', cmd: `jsn catalogitems describe ${id}`, description: 'Inspect catalog inputs and pricing' },
+    { action: 'preview', cmd: `jsn catalogitems order ${id} --dry-run --variables-file variables.json`, description: 'Preview an order without submitting' }];
+}
+
+export function catalogOrderCommands(wrap) {
+  return [
+    { command: 'search <text>', describe: 'Find requestable items through the Service Catalog API',
+      builder: y => y.positional('text', { type: 'string' }).option('limit', { type: 'number', default: 20, describe: 'Maximum items (1–100)' }),
+      handler: wrap(async (argv, app) => {
+        if (typeof argv.text !== 'string' || !argv.text.trim()) throw errUsage('Provide nonempty catalog search text.');
+        if (!Number.isInteger(argv.limit) || argv.limit < 1 || argv.limit > 100) throw errUsage('--limit must be from 1 to 100.');
+        const params = new URLSearchParams({ sysparm_text: argv.text.trim(), sysparm_limit: String(argv.limit) });
+        const response = await app.sdk.request(`${app.sdk.baseURL}${API}?${params}`, { method: 'GET' });
+        if (!Array.isArray(response?.result) || response.result.some(i => !object(i) || !ID.test(i.sys_id || ''))) throw errAPI(200, 'Catalog API returned no valid item list.');
+        emit(app, argv, { items: response.result, count: response.result.length, limit: argv.limit,
+          possibly_truncated: response.result.length === argv.limit }, `${response.result.length} catalog item(s)`,
+        response.result.flatMap(i => itemHints(i.sys_id).slice(0, 1)));
+      }) },
+    { command: 'describe <id>', aliases: ['inputs'], describe: 'Read requestable item details, pricing and variable definitions',
+      builder: y => y.positional('id', { type: 'string' }),
+      handler: wrap(async (argv, app) => {
+        const item = await describe(app, argv.id);
+        emit(app, argv, item, item.name || item.short_description || argv.id, itemHints(argv.id));
+      }) },
+    { command: 'order <id>', describe: 'Submit a catalog order with explicit confirmation',
+      builder: y => y.positional('id', { type: 'string' })
+        .option('variables', { type: 'string', describe: 'JSON object of catalog variable names/values' })
+        .option('variables-file', { type: 'string', describe: 'Read the variables object from a JSON file' })
+        .option('quantity', { type: 'number', default: 1, describe: 'Positive integer quantity (max 1000)' })
+        .option('requested-for', { type: 'string', describe: 'User sys_id; instance delegation rules still apply' })
+        .option('dry-run', { type: 'boolean', default: false, describe: 'Read item details and preview variable names; no order is submitted' })
+        .epilogue('Use describe to inspect variables first. Server-side rules validate the order; a preview does not prove submission will succeed. Existing create/list/show commands manage definitions. Orders require a write-enabled profile, including dry runs. No application/update-set selection is needed.'),
+      handler: wrap(async (argv, app) => {
+        requireId(argv.id);
+        if (!Number.isInteger(argv.quantity) || argv.quantity < 1 || argv.quantity > 1000) throw errUsage('--quantity must be an integer from 1 to 1000.');
+        const requestedFor = argv.requestedFor ?? argv['requested-for'];
+        if (requestedFor !== undefined && !ID.test(requestedFor)) throw errUsage('--requested-for requires a user sys_id.');
+        const file = argv.variablesFile ?? argv['variables-file'];
+        if (argv.variables !== undefined && file !== undefined) throw errUsage('Choose --variables or --variables-file, not both.');
+        const variables = argv.variables !== undefined || file !== undefined
+          ? parseDataArg({ data: argv.variables, 'data-file': file }) : {};
+        if (!object(variables)) throw errUsage('Catalog variables must be a JSON object.');
+        const item = await describe(app, argv.id);
+        if (item.sys_class_name && item.sys_class_name !== 'sc_cat_item') throw errUsage('order supports standard catalog items; record producers and order guides need their own submission workflows.');
+        if (item.active === false || item.active === 'false' || item.can_order === false) throw errUsage('This item is not currently orderable.');
+        const plan = { item_id: argv.id, name: item.name || item.short_description, quantity: argv.quantity,
+          requested_for: requestedFor || null, variable_names: Object.keys(variables) };
+        if (argv.dryRun ?? argv['dry-run']) return emit(app, argv, { ...plan, submitted: false, server_validation: 'not performed' }, 'Catalog order preview; nothing submitted', itemHints(argv.id));
+        const rerun = ['catalogitems', 'order', argv.id, '--quantity', String(argv.quantity),
+          ...(requestedFor ? ['--requested-for', requestedFor] : []),
+          ...(file ? ['--variables-file', file] : Object.keys(variables).length ? ['--variables-file', '<variables.json>'] : [])];
+        try {
+          await confirmDelete(app, argv, `Order ${argv.quantity} × ${plan.name || argv.id}${requestedFor ? ` for ${requestedFor}` : ''}?`, { rerun });
+        } catch (error) {
+          if (error.message === 'Deletion cancelled') throw errUsage('Catalog order cancelled.');
+          throw error;
+        }
+        const body = { sysparm_quantity: argv.quantity, variables, ...(requestedFor ? { sysparm_requested_for: requestedFor } : {}) };
+        let response;
+        try {
+          response = await app.sdk.request(`${app.sdk.baseURL}${API}/${argv.id}/order_now`, { method: 'POST', body: JSON.stringify(body) });
+        } catch (error) {
+          if (error.status >= 400 && error.status < 500 && error.status !== 408) throw errAPI(error.status, 'Catalog order was rejected. Check item access, required variables and requested-for eligibility.');
+          throw errAPI(error.status || 0, 'Catalog submission did not return a confirmed order. Inspect your requests before retrying; the order may have been placed.');
+        }
+        const result = response?.result;
+        const requestId = result?.request_id || result?.sys_id, number = result?.request_number || result?.number;
+        if (!object(result) || result.error || !ID.test(requestId || '') || typeof number !== 'string' || !number.trim()) throw errAPI(200, 'Catalog response did not confirm an order identity. Inspect your requests before retrying; do not resubmit automatically.');
+        emit(app, argv, { item_id: argv.id, quantity: argv.quantity, request_id: requestId, request_number: number, submitted: true },
+          `Ordered: ${number}`, [{ action: 'request', cmd: `jsn records get --table sc_request --sys-id ${requestId}`, description: 'Read the request header' },
+            { action: 'items', cmd: `jsn requests list --query ${quoteShellArg(`request=${requestId}`)}`, description: 'Track the requested items' }]);
+      }) },
+  ];
+}

package/src/commands/catalog.js

@@ -1,9 +1,10 @@
-import { getStringField, interactiveList, resolveItemOptionType } from '../helpers.js';
+import { getStringField, interactiveList, resolveItemOptionType, formatCommandList, quoteShellArg } from '../helpers.js';
+import { catalogOrderCommands } from './catalog-order.js';
 import { resolveSysId } from '../resolve-record.js';
 import { declareCapabilities } from '../capabilities.js';
 import { enrichCatalogItem, buildCatalogFormatted } from './catalog/enrich.js';
 
-declareCapabilities('catalogitems', { mutationSubcommands: ['create'] });
+declareCapabilities('catalogitems', { mutationSubcommands: ['create', 'order'], mutationContextExemptSubcommands: ['order'], localPreviewSubcommands: ['order'] });
 
 export function catalogCmd(wrap) {
   return {
@@ -11,6 +12,7 @@ export function catalogCmd(wrap) {
     aliases: ['ci'],
     describe: 'Manage Service Catalog items',
     builder: (yargs) => {
+      for (const command of catalogOrderCommands(wrap)) yargs.command(command);
       return yargs
         .command({
           command: 'create',
@@ -148,14 +150,10 @@ export function catalogCmd(wrap) {
           }),
         });
     },
-    handler: () => {
-      console.log('Service Catalog management.');
-      console.log('');
-      console.log('Commands:');
-      console.log('  create     Create a catalog item');
-      console.log('  list       Browse catalog items');
-      console.log('  show <id>  Show catalog item');
-    },
+    handler: wrap(async (argv, app) => app.ok({ subcommands: argv.subcommands || [],
+      _formatted: formatCommandList({ title: 'Service Catalog', commands: argv.subcommands || [] }) },
+    { summary: 'Service Catalog: search, describe and order items; manage definitions with create/list/show',
+      breadcrumbs: [{ action: 'search', cmd: 'jsn catalogitems search <text>' + (argv.profile ? ` --profile ${quoteShellArg(argv.profile)}` : argv.instance ? ` --instance ${quoteShellArg(argv.instance)}` : ''), description: 'Find requestable items' }] })),
   };
 }
 

package/src/commands/knowledge.js

@@ -0,0 +1,75 @@
+import TurndownService from 'turndown';
+import { formatCommandList, quoteShellArg } from '../helpers.js';
+import { errAPI, errUsage } from '../errors.js';
+
+const API = '/api/sn_km_api/knowledge/articles';
+const markdown = new TurndownService();
+const sysId = /^[a-f0-9]{32}$/i;
+const articleId = value => typeof value === 'string' && (sysId.test(value) || /^KB\d+$/i.test(value));
+
+function emit(app, argv, data, summary, breadcrumbs = []) {
+  const connection = argv.profile ? ` --profile ${quoteShellArg(argv.profile)}`
+    : argv.instance ? ` --instance ${quoteShellArg(argv.instance)}` : '';
+  app.ok(data, { summary, breadcrumbs: breadcrumbs.map(h => ({ ...h, cmd: h.cmd + connection })) });
+}
+
+async function read(sdk, path, params) {
+  const response = await sdk.request(`${sdk.baseURL}${API}${path}?${params}`, { method: 'GET' });
+  const result = response?.result;
+  if (!result || typeof result !== 'object' || Array.isArray(result)) throw errAPI(200, 'Malformed Knowledge API response.');
+  const code = result.meta?.status?.code;
+  if (code !== undefined && Number(code) !== 200) throw errAPI(Number(code) || 500, 'Knowledge API rejected the request.');
+  return result;
+}
+
+export function knowledgeCmd(wrap) {
+  return {
+    command: 'knowledge [subcommand]', aliases: ['kb'],
+    describe: 'Search and read knowledge articles through the Knowledge API',
+    handler: wrap(async (argv, app) => emit(app, argv,
+      { subcommands: argv.subcommands || [], _formatted: formatCommandList({ title: 'Knowledge articles', commands: argv.subcommands || [] }) },
+      'Search and read knowledge articles', [{ action: 'search', cmd: 'jsn knowledge search <text>', description: 'Find accessible articles' }])),
+    builder: y => y
+      .epilogue('Requires the Knowledge API (sn_km_api). Uses its access checks; no fallback to direct knowledge-table reads. Reading does not request view-count updates.')
+      .command({ command: 'search <text>', describe: 'Search accessible knowledge articles',
+        builder: p => p.positional('text', { type: 'string', describe: 'Search text; quote multiple words' })
+          .option('limit', { type: 'number', default: 20, describe: 'Maximum articles (1–100)' })
+          .option('offset', { type: 'number', default: 0, describe: 'Starting result offset' })
+          .option('kb', { type: 'string', describe: 'Comma-separated knowledge-base sys_ids' })
+          .option('language', { type: 'string', describe: 'Two-letter language codes, comma-separated, or all' }),
+        handler: wrap(async (argv, app) => {
+          if (typeof argv.text !== 'string' || !argv.text.trim()) throw errUsage('Provide nonempty search text.');
+          if (!Number.isInteger(argv.limit) || argv.limit < 1 || argv.limit > 100) throw errUsage('--limit must be from 1 to 100.');
+          if (!Number.isInteger(argv.offset) || argv.offset < 0) throw errUsage('--offset must be a nonnegative integer.');
+          if (argv.kb !== undefined && !String(argv.kb).split(',').every(id => sysId.test(id))) throw errUsage('--kb requires knowledge-base sys_ids.');
+          if (argv.language !== undefined && !/^(all|[a-z]{2}(,[a-z]{2})*)$/i.test(argv.language)) throw errUsage('Use two-letter --language codes or all.');
+          const params = new URLSearchParams({ query: argv.text.trim(), limit: String(argv.limit), offset: String(argv.offset) });
+          if (argv.kb) params.set('kb', argv.kb);
+          if (argv.language) params.set('language', argv.language);
+          const result = await read(app.sdk, '', params);
+          if (!Array.isArray(result.articles) || result.articles.some(a => !a || typeof a !== 'object' || Array.isArray(a))) throw errAPI(200, 'Knowledge API returned no valid article list.');
+          const breadcrumbs = result.articles.flatMap(a => {
+            const id = articleId(a.number) ? a.number : String(a.id || '').replace(/^kb_knowledge:/, '');
+            return articleId(id) ? [{ action: 'show', cmd: `jsn knowledge show ${id}`, description: a.title || id }] : [];
+          });
+          const base = `jsn knowledge search ${quoteShellArg(argv.text.trim())} --limit ${argv.limit}`
+            + (argv.kb ? ` --kb ${quoteShellArg(argv.kb)}` : '') + (argv.language ? ` --language ${quoteShellArg(argv.language)}` : '');
+          const total = result.meta?.count;
+          const hasMore = typeof total === 'number' ? argv.offset + result.articles.length < total : result.articles.length === argv.limit;
+          if (hasMore) breadcrumbs.push({ action: 'next', cmd: `${base} --offset ${argv.offset + argv.limit}`, description: 'Next result page' });
+          emit(app, argv, { ...result, count: result.articles.length,
+            _formatted: result.articles.map(a => `${a.number || a.id || ''}  ${a.title || ''}\n${a.snippet || ''}`).join('\n\n') || 'No accessible articles matched.' },
+          `${result.articles.length} knowledge article(s)`, breadcrumbs);
+        }) })
+      .command({ command: 'show <id>', describe: 'Read an article by KB number or sys_id',
+        builder: p => p.positional('id', { type: 'string' }),
+        handler: wrap(async (argv, app) => {
+          if (!articleId(argv.id)) throw errUsage('Use a KB number or full article sys_id.');
+          const article = await read(app.sdk, `/${encodeURIComponent(argv.id)}`, new URLSearchParams());
+          if (!sysId.test(article.sys_id || '') || typeof article.content !== 'string') throw errAPI(200, 'Knowledge API returned no readable article content.');
+          emit(app, argv, { ...article, _formatted: `${article.number || argv.id}: ${article.short_description || ''}\n\n${markdown.turndown(article.content)}` },
+            article.short_description || article.number || argv.id,
+            [{ action: 'search', cmd: 'jsn knowledge search <text>', description: 'Find more articles' }]);
+        }) }),
+  };
+}

package/src/help.js

@@ -28,6 +28,7 @@ function renderGroup(name, commands) {
 }
 
 const CORE_COMMANDS = [
+  { name: 'knowledge', alias: 'kb', desc: 'Search and read knowledge articles' },
   { name: 'incidents', alias: 'inc', desc: 'Manage incidents' },
   { name: 'changes', alias: 'chg', desc: 'Manage change requests' },
   { name: 'requests', alias: 'req', desc: 'Manage service catalog requests' },