@jacebenson/jsn 4.3.13-dev.104.1 → 4.3.13-dev.106.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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "4.3.13-dev.104.1",
+  "version": "4.3.13-dev.106.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

@@ -5,7 +5,7 @@ const BASIC_COMMANDS = new Set([
   'knowledge',
   'groups', 'groupmembers', 'grouproles', 'users', 'setup', 'auth', 'skill',
   'cmdb',
-  'version', 'docs', 'history', 'discover', 'completion',
+  'version', 'upgrade', 'docs', 'history', 'discover', 'completion',
   'catalogitems',
 ]);
 

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;