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

package/README.md

@@ -23,8 +23,12 @@ npm install -g @jacebenson/jsn@dev
 
 Dev builds check the dev channel for updates during normal use, at most once
 per day. Run `jsn version --check` to check immediately. To install the newest
-dev build, run `npm install -g @jacebenson/jsn@dev` again. Updates are manual.
-Return to stable with `npm install -g @jacebenson/jsn@latest`.
+dev build, run `jsn upgrade` (alias: `jsn update`). It preserves your installed
+channel and skips installation when no newer version is available. Use
+`--dry-run` to print the npm command without network access or installation,
+`--force` to reinstall, or `--channel dev|latest` to switch channels explicitly.
+For example, `jsn upgrade --channel latest` returns to stable. npm installation
+permissions still apply; the command does not elevate privileges automatically.
 
 Pushes to `main` promote the commit to `dev` and publish a tested prerelease
 under npm's `dev` tag. Versions include the workflow run number and attempt
@@ -83,6 +87,15 @@ an explicitly selected profile or instance. `updatesets show` also offers a scan
 hint. Recommendation/generation of new checks is not part of this command;
 JSN contains no AI and does not infer missing business requirements.
 
+### CMDB search
+
+`jsn cmdb search "web" --profile work` searches names, FQDNs, IP addresses and
+serial numbers on `cmdb_ci`. Use `--class cmdb_ci_server` for an exact class
+match (excluding subclasses), and bounded `--limit`/`--offset` pagination.
+Search text is literal; encoded-query operators and query scripts are rejected.
+Existing `cmdb list --query` remains available for deliberate encoded queries.
+Results include show/relationship hints and preserve the selected connection.
+
 ### Supported versions
 
 Only the current release and the two preceding releases in each channel are

package/package.json

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

package/src/cli.js

@@ -39,6 +39,7 @@ import { transactionsCmd } from './commands/transactions.js';
 import { platformCmd } from './commands/platform.js';
 import { codesearchCmd } from './commands/codesearch.js';
 import { versionCmd } from './commands/version.js';
+import { upgradeCmd } from './commands/upgrade.js';
 import { skillCmd, checkSkill } from './commands/skill.js';
 import { getVersion, checkLatest, getReleaseChannel, getInstallCommand } from './commands/version.js';
 import { docsCmd } from './commands/docs/docs.js';
@@ -438,6 +439,7 @@ export function buildCLI() {
     .command(skillCmd(wrap))
     .command(docsCmd(wrap))
     .command(versionCmd(wrap))
+    .command(upgradeCmd(wrap))
     .command(discoverCmd(wrap, (argv) => visibleCommandRegistry(cliInstance.commandRegistry(), app.config, argv)))
     .demandCommand(1, 'You must specify a command')
     // Completion plumbing under a hidden command name, so the explicit

package/src/command-audience.js

@@ -4,7 +4,8 @@ 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',
+  'cmdb',
+  'version', 'upgrade', 'docs', 'history', 'discover', 'completion',
   'catalogitems',
 ]);
 

package/src/commands/cmdb-search.js

@@ -0,0 +1,38 @@
+import { assertSafeExactMatch, quoteShellArg } from '../helpers.js';
+import { errAPI, errUsage } from '../errors.js';
+
+const FIELDS = ['name', 'fqdn', 'ip_address', 'serial_number'];
+const raw = v => v && typeof v === 'object' ? v.value : v;
+
+export function cmdbSearchCmd(wrap) {
+  return { command: 'search <text>', describe: 'Find CIs by name, FQDN, IP address, or serial number',
+    builder: y => y.positional('text', { type: 'string', describe: 'Literal text; quote multiple words' })
+      .option('class', { type: 'string', describe: 'Exact CI class name (not descendants)' })
+      .option('limit', { type: 'number', default: 20, describe: 'Maximum CIs (1–100)' })
+      .option('offset', { type: 'number', default: 0, describe: 'Starting result offset' }),
+    handler: wrap(async (argv, app) => {
+      if (typeof argv.text !== 'string' || !argv.text.trim()) throw errUsage('Provide nonempty CI search text.');
+      const text = argv.text.trim();
+      assertSafeExactMatch(text);
+      if ([...text].some(c => c.codePointAt(0) < 32 || c.codePointAt(0) === 127) || /javascript:/i.test(text)) throw errUsage('Search text must not contain query scripts or control characters.');
+      if (argv.class !== undefined && !/^[a-z][a-z0-9_]*$/.test(argv.class)) throw errUsage('--class must be an exact CI table name.');
+      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.');
+      // Repeat the class restriction in each OR branch: no branch may escape it.
+      const query = FIELDS.map(f => `${f}LIKE${text}${argv.class ? `^sys_class_name=${argv.class}` : ''}`).join('^NQ') + '^ORDERBYname^ORDERBYsys_id';
+      const params = new URLSearchParams({ sysparm_query: query, sysparm_limit: String(argv.limit + 1), sysparm_offset: String(argv.offset),
+        sysparm_fields: 'sys_id,name,sys_class_name,fqdn,ip_address,serial_number', sysparm_display_value: 'all' });
+      const rows = await app.sdk.listStrict('cmdb_ci', params);
+      if (!Array.isArray(rows) || rows.some(r => !r || typeof r !== 'object' || Array.isArray(r))) throw errAPI(200, 'CMDB search returned no valid record list.');
+      const hasMore = rows.length > argv.limit, records = rows.slice(0, argv.limit);
+      const connection = argv.profile ? ` --profile ${quoteShellArg(argv.profile)}` : argv.instance ? ` --instance ${quoteShellArg(argv.instance)}` : '';
+      const breadcrumbs = records.flatMap(r => /^[a-f0-9]{32}$/i.test(raw(r.sys_id) || '') ? [
+        { action: 'show', cmd: `jsn cmdb show ${raw(r.sys_id)}`, description: String(raw(r.name) || 'Inspect CI') },
+        { action: 'relationships', cmd: `jsn cmdb relationships --ci ${raw(r.sys_id)}`, description: 'Inspect CI dependencies' },
+      ] : []);
+      if (hasMore) breadcrumbs.push({ action: 'next', cmd: `jsn cmdb search ${quoteShellArg(text)} --limit ${argv.limit} --offset ${argv.offset + argv.limit}${argv.class ? ` --class ${argv.class}` : ''}`, description: 'Next matching CIs' });
+      app.ok({ table: 'cmdb_ci', search: text, fields: FIELDS, records, count: records.length,
+        pagination: { limit: argv.limit, offset: argv.offset, has_more: hasMore } },
+      { summary: `${records.length} matching CI(s)`, breadcrumbs: breadcrumbs.map(h => ({ ...h, cmd: h.cmd + connection })) });
+    }) };
+}

package/src/commands/cmdb.js

@@ -15,6 +15,7 @@ import {
   resolveFieldsParam,
 } from '../helpers.js';
 import { errNotFound, errUsage } from '../errors.js';
+import { cmdbSearchCmd } from './cmdb-search.js';
 
 const SYS_ID_RE = /^[0-9a-f]{32}$/i;
 const MAX_DEPTH = 5;
@@ -371,6 +372,7 @@ export function cmdbCmd(wrap) {
     }),
     builder: (yargs) => {
       return yargs
+        .command(cmdbSearchCmd(wrap))
         .command({
           command: 'list',
           describe: 'List CIs from the CMDB (cmdb_ci)',

package/src/commands/upgrade.js

@@ -0,0 +1,69 @@
+import { spawnSync } from 'node:child_process';
+import { declareCapabilities } from '../capabilities.js';
+import { AppError, CodeAPI, CodeNetwork } from '../errors.js';
+import { checkLatest, getReleaseChannel, getVersion } from './version.js';
+
+for (const name of ['upgrade', 'update']) {
+  declareCapabilities(name, { noInstance: true, skipDailyChecks: true });
+}
+
+function installPackage(args, { structured }) {
+  const result = spawnSync('npm', args, { stdio: structured ? 'pipe' : 'inherit', encoding: 'utf8' });
+  if (result.error || result.status !== 0) {
+    throw new AppError(CodeAPI, 'npm could not upgrade jsn.', 'Check npm installation permissions and connectivity, then retry.');
+  }
+}
+
+function isNewer(candidate, installed) {
+  const parse = (value) => {
+    const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(value);
+    if (!match) throw new AppError(CodeAPI, 'The registry returned an invalid package version.');
+    return { core: match.slice(1, 4).map(Number), pre: match[4]?.split('.') };
+  };
+  const a = parse(candidate), b = parse(installed);
+  for (let i = 0; i < 3; i++) {
+    if (a.core[i] !== b.core[i]) return a.core[i] > b.core[i];
+  }
+  if (!a.pre || !b.pre) return !a.pre && Boolean(b.pre);
+  for (let i = 0; i < Math.max(a.pre.length, b.pre.length); i++) {
+    if (a.pre[i] === b.pre[i]) continue;
+    if (a.pre[i] === undefined) return false;
+    if (b.pre[i] === undefined) return true;
+    const an = /^\d+$/.test(a.pre[i]), bn = /^\d+$/.test(b.pre[i]);
+    if (an && bn) return Number(a.pre[i]) > Number(b.pre[i]);
+    if (an !== bn) return !an;
+    return a.pre[i] > b.pre[i];
+  }
+  return false;
+}
+
+export function upgradeCmd(wrap, { version = getVersion, check = checkLatest, install = installPackage } = {}) {
+  return {
+    command: 'upgrade',
+    aliases: ['update'],
+    describe: 'Upgrade jsn through npm (preserves the installed release channel)',
+    builder: (y) => y
+      .option('channel', { type: 'string', choices: ['dev', 'latest'], describe: 'Choose the npm release channel' })
+      .option('dry-run', { type: 'boolean', describe: 'Show the install command without installing' })
+      .option('force', { type: 'boolean', describe: 'Reinstall even when the selected version is not newer' }),
+    handler: wrap(async (argv, app) => {
+      const current = version();
+      const channel = argv.channel || getReleaseChannel(current);
+      const args = ['install', '-g', `@jacebenson/jsn@${channel}`];
+      const command = `npm ${args.join(' ')}`;
+      if (argv.dryRun || argv['dry-run']) {
+        app.ok({ version: current, channel, dryRun: true, installCmd: command }, { summary: command });
+        return;
+      }
+      const latest = await check({ version: current, channel });
+      if (!latest) throw new AppError(CodeNetwork, 'Could not check the npm release channel.', 'Check connectivity and retry; use --dry-run to inspect the command.');
+      const switching = argv.channel && channel !== getReleaseChannel(current);
+      if (!argv.force && !switching && !isNewer(latest, current)) {
+        app.ok({ version: current, latest, channel, upToDate: true }, { summary: `jsn ${current} — no newer version available` });
+        return;
+      }
+      await install(args, { structured: Boolean(!process.stdout.isTTY || argv.json || argv.get || argv.format === 'json') });
+      app.ok({ previousVersion: current, version: latest, channel, upgraded: true }, { summary: `Installed jsn from the ${channel} channel (registry version ${latest})` });
+    }),
+  };
+}

package/src/commands/version.js

@@ -32,13 +32,13 @@ export function cancelBackgroundChecks() {
   backgroundChecks.clear();
 }
 
-export async function checkLatest({ timeout = 1500, background = false, version = getVersion() } = {}) {
+export async function checkLatest({ timeout = 1500, background = false, version = getVersion(), channel = getReleaseChannel(version) } = {}) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeout);
   timer.unref();
   if (background) backgroundChecks.add(controller);
   try {
-    const res = await fetch(`https://registry.npmjs.org/${NPM_PKG}/${getReleaseChannel(version)}`, { signal: controller.signal });
+    const res = await fetch(`https://registry.npmjs.org/${NPM_PKG}/${channel}`, { signal: controller.signal });
     if (!res.ok) return null;
     const data = await res.json();
     return typeof data.version === 'string' ? data.version : null;