@jacebenson/jsn 4.3.7-dev.20 → 4.3.7-dev.22

package/package.json

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

package/src/cli.js

@@ -69,6 +69,7 @@ import { b4rulesCmd } from './commands/b4rules.js';
 import { atfCmd } from './commands/atf.js';
 import { approvalsCmd } from './commands/approvals.js';
 import { perfCmd } from './commands/perf.js';
+import { midserversCmd } from './commands/midservers.js';
 import { diffCmd } from './commands/diff.js';
 import { graphqlCmd } from './commands/graphql.js';
 
@@ -373,6 +374,7 @@ export function buildCLI() {
     .command(atfCmd(wrap))
     .command(approvalsCmd(wrap))
     .command(perfCmd(wrap))
+    .command(midserversCmd(wrap))
     .command(diffCmd(wrap))
     .command(graphqlCmd(wrap))
     .command(evalCmd(wrap))

package/src/commands/midservers.js

@@ -0,0 +1,340 @@
+import { input, password as passwordPrompt, select } from '@inquirer/prompts';
+import { confirmDelete, formatRecordForDisplay, getStringField, interactiveList, canPrompt } from '../helpers.js';
+import { FormatAuto } from '../output.js';
+import { declareCapabilities } from '../capabilities.js';
+import { resolveRecord, unwrapSysId } from '../resolve-record.js';
+import { dockerComposeAvailable, installDockerMidServer, validateMidCredentials } from '../midserver-install.js';
+
+const AGENT_TABLE = 'ecc_agent';
+const QUEUE_TABLE = 'ecc_queue';
+const LIST_FIELDS = ['sys_id', 'name', 'status', 'host_name', 'ip_address', 'version', 'validated', 'last_heartbeat', 'sys_updated_on'];
+const DEFAULT_TIMEOUT = 120000;
+const DEFAULT_INTERVAL = 2000;
+
+declareCapabilities('midservers', { mutationSubcommands: ['add', 'remove', 'execute'] });
+
+function agentName(record) {
+  const name = getStringField(record, 'name');
+  return name.startsWith('mid.server.') ? name : `mid.server.${name}`;
+}
+
+function queueValue(value) {
+  return value && typeof value === 'object' ? (value.value || value.display_value || '') : String(value || '');
+}
+
+function escapeXml(value) {
+  return String(value)
+    .replaceAll('&', '&')
+    .replaceAll('"', '"')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll("'", '&apos;');
+}
+
+export function buildCommandPayload(command) {
+  return `<parameters><parameter name="name" value="${escapeXml(command)}"/></parameters>`;
+}
+
+function decodeXml(value) {
+  return String(value || '')
+    .replaceAll('&lt;', '<')
+    .replaceAll('&gt;', '>')
+    .replaceAll('&quot;', '"')
+    .replaceAll('&apos;', "'")
+    .replaceAll('&amp;', '&');
+}
+
+export function parseCommandResult(payload) {
+  if (!payload) return { stdout: '', stderr: '' };
+  const result = payload.match(/<result\b[^>]*>([\s\S]*?)<\/result>/i)?.[1] || payload;
+  const stdout = result.match(/<stdout\b[^>]*>([\s\S]*?)<\/stdout>/i)?.[1] || '';
+  const stderr = result.match(/<stderr\b[^>]*>([\s\S]*?)<\/stderr>/i)?.[1] || '';
+  return { stdout: decodeXml(stdout), stderr: decodeXml(stderr) };
+}
+
+async function waitForCommandResult(sdk, outputSysId, timeoutMs, intervalMs) {
+  const started = Date.now();
+  while (Date.now() - started <= timeoutMs) {
+    const params = new URLSearchParams({
+      sysparm_query: `response_to=${outputSysId}^queue=input`,
+      sysparm_limit: '1',
+      sysparm_display_value: 'all',
+      sysparm_fields: 'sys_id,state,error,payload,name,topic,queue,agent,created_on,processed',
+    });
+    const records = await sdk.list(QUEUE_TABLE, params);
+    if (records.length > 0) return records[0];
+    await new Promise(resolve => setTimeout(resolve, intervalMs));
+  }
+  const error = new Error(`Timed out waiting for MID Server response to ECC Queue record ${outputSysId}`);
+  error.code = 'midserver_timeout';
+  throw error;
+}
+
+async function resolveMidServer(sdk, identifier) {
+  try {
+    return await resolveRecord(sdk, {
+      table: AGENT_TABLE,
+      identifier,
+      matchField: 'name',
+      resource: 'MID Server',
+    });
+  } catch (error) {
+    if (error.code !== 'not_found' || identifier.startsWith('mid.server.')) throw error;
+    return resolveRecord(sdk, {
+      table: AGENT_TABLE,
+      identifier: `mid.server.${identifier}`,
+      matchField: 'name',
+      resource: 'MID Server',
+    });
+  }
+}
+
+async function listAgents(app, argv) {
+  const columns = argv.columns
+    ? [...new Set(argv.columns.split(',').map(column => column.trim()).filter(Boolean))]
+    : LIST_FIELDS;
+  const query = argv.query || '';
+
+  if (canPrompt() && app.output.getFormat() === FormatAuto && !query) {
+    const picked = await interactiveList({
+      app,
+      table: AGENT_TABLE,
+      singular: 'MID Server',
+      columns,
+      limit: argv.limit,
+      labelField: 'name',
+      message: 'Select a MID Server',
+      formatLabel: (record) => {
+        const name = getStringField(record, 'name') || getStringField(record, 'sys_id');
+        const status = getStringField(record, 'status');
+        return status ? `${name} [${status}]` : name;
+      },
+    });
+    if (picked === undefined || picked === null) return;
+    picked._context = { instance_url: app.getEffectiveInstance(), table: AGENT_TABLE };
+    app.ok(picked, {
+      summary: `MID Server: ${getStringField(picked, 'name') || getStringField(picked, 'sys_id')}`,
+      breadcrumbs: [{ action: 'list', cmd: 'jsn midservers list', description: 'Back to all MID Servers' }],
+    });
+    return;
+  }
+
+  const params = new URLSearchParams({
+    sysparm_limit: String(argv.limit),
+    sysparm_display_value: 'all',
+    sysparm_fields: ['sys_id', ...columns.filter(column => column !== 'sys_id')].join(','),
+    sysparm_query: query ? `${query}^ORDERBYDESCsys_updated_on` : 'ORDERBYname',
+  });
+  const records = await app.sdk.list(AGENT_TABLE, params);
+  app.ok({
+    table: AGENT_TABLE,
+    count: records.length,
+    columns,
+    records: records.map(record => formatRecordForDisplay(record, columns)),
+    context: { instance_url: app.getEffectiveInstance() },
+  }, { summary: `${records.length} MID Server(s)` });
+}
+
+export function assertMidServerUp(record) {
+  const name = getStringField(record, 'name') || getStringField(record, 'sys_id') || 'MID Server';
+  const status = getStringField(record, 'status');
+  if (status.toLowerCase() !== 'up') {
+    const error = new Error(`MID Server '${name}' is not Up (status: ${status || 'unknown'}). Start or install it before executing a command.`);
+    error.code = 'midserver_not_up';
+    throw error;
+  }
+}
+
+async function promptMidCredentials(app, argv) {
+  if (!canPrompt()) throw new Error('MID Server installation is interactive. Run it from a terminal.');
+  let username = argv.username || '';
+  while (true) {
+    username = username || (await input({
+      message: 'MID Server username:',
+      validate: value => value.trim() ? true : 'Username is required',
+    })).trim();
+    const password = await passwordPrompt({
+      message: 'MID Server password:',
+      mask: '*',
+      validate: value => value ? true : 'Password is required',
+    });
+    try {
+      const validation = await validateMidCredentials(app.getEffectiveInstance(), username, password);
+      return { username, password, releaseName: validation.releaseName };
+    } catch (error) {
+      const answer = await input({ message: `${error.message}. Press Enter to retry or Q to quit:` });
+      if (answer.trim().toLowerCase() === 'q') {
+        const quit = new Error('MID Server installation cancelled');
+        quit.code = 'cancelled';
+        throw quit;
+      }
+      username = argv.username || '';
+    }
+  }
+}
+
+async function waitForMidServerUp(app, name, timeoutMs, intervalMs) {
+  const started = Date.now();
+  const fullName = `mid.server.${name.replace(/^mid\.server\./, '')}`;
+  while (Date.now() - started <= timeoutMs) {
+    const params = new URLSearchParams({
+      sysparm_query: `name=${fullName}`,
+      sysparm_limit: '1',
+      sysparm_display_value: 'all',
+      sysparm_fields: 'sys_id,name,status,host_name,version,last_heartbeat',
+    });
+    const records = await app.sdk.list(AGENT_TABLE, params);
+    if (records[0] && getStringField(records[0], 'status').toLowerCase() === 'up') return records[0];
+    await new Promise(resolve => setTimeout(resolve, intervalMs));
+  }
+  throw new Error(`MID Server '${fullName}' did not report Up within ${timeoutMs}ms`);
+}
+
+export function midserversCmd(wrap) {
+  return {
+    command: 'midservers [subcommand]',
+    aliases: ['midserver', 'mid'],
+    describe: 'Manage ServiceNow MID Servers and run commands through them',
+    builder: (y) => y
+      .command({
+        command: 'list',
+        aliases: ['ls'],
+        describe: 'List MID Servers',
+        builder: (b) => b
+          .option('query', { type: 'string', describe: 'Encoded query against ecc_agent' })
+          .option('columns', { type: 'string', describe: 'Comma-separated fields' })
+          .option('limit', { alias: 'l', type: 'number', default: 50, describe: 'Max records' }),
+        handler: wrap(async (argv, app) => {
+          await listAgents(app, argv);
+        }),
+      })
+      .command({
+        command: 'show <identifier>',
+        aliases: ['get'],
+        describe: 'Show a MID Server by name or sys_id',
+        handler: wrap(async (argv, app) => {
+          const record = await resolveMidServer(app.sdk, argv.identifier);
+          record._context = { instance_url: app.getEffectiveInstance(), table: AGENT_TABLE };
+          app.ok(record, { summary: `MID Server: ${getStringField(record, 'name') || argv.identifier}` });
+        }),
+      })
+      .command({
+        command: 'add',
+        describe: 'Install and verify a MID Server',
+        builder: (b) => b
+          .option('name', { type: 'string', describe: 'MID Server name (prompted when omitted)' })
+          .option('username', { type: 'string', describe: 'MID Server username (password is always prompted)' })
+          .option('install-method', { type: 'string', choices: ['docker', 'direct'], describe: 'Installation method (prompted when omitted)' })
+          .option('directory', { type: 'string', describe: 'Docker installation directory' })
+          .option('wait-timeout', { type: 'number', default: 120000, describe: 'How long to wait for the MID Server to report Up' })
+          .option('wait-interval', { type: 'number', default: 3000, describe: 'MID Server status polling interval in milliseconds' }),
+        handler: wrap(async (argv, app) => {
+          app.requireInstance();
+          const credentials = await promptMidCredentials(app, argv);
+          const name = argv.name || (await input({
+            message: 'MID Server name:',
+            validate: value => value.trim() ? true : 'MID Server name is required',
+          })).trim();
+          const dockerAvailable = dockerComposeAvailable();
+          const installMethod = argv['install-method'] || await select({
+            message: dockerAvailable
+              ? 'Docker and Docker Compose detected. How should the MID Server be installed?'
+              : 'Docker was not detected. How should the MID Server be installed?',
+            choices: dockerAvailable
+              ? [
+                { name: 'Docker (recommended)', value: 'docker' },
+                { name: 'Direct install (not available yet)', value: 'direct' },
+              ]
+              : [
+                { name: 'Install Docker first', value: 'install-docker' },
+                { name: 'Direct install (not available yet)', value: 'direct' },
+              ],
+          });
+          if (installMethod === 'direct') throw new Error('Direct MID Server installation is not implemented yet. Choose Docker.');
+          if (installMethod === 'install-docker') throw new Error('Automatic Docker installation is not implemented yet. Install Docker and Compose, then run this command again.');
+
+          const installation = await installDockerMidServer({
+            instanceURL: app.getEffectiveInstance(),
+            username: credentials.username,
+            password: credentials.password,
+            name,
+            releaseName: credentials.releaseName,
+            directory: argv.directory,
+          });
+          let record;
+          try {
+            record = await waitForMidServerUp(app, installation.name, Math.max(1, argv['wait-timeout']), Math.max(500, argv['wait-interval']));
+          } catch (error) {
+            try { installation.rollback(); } catch { /* preserve the verification error */ }
+            throw error;
+          }
+          app.ok({
+            installation: 'docker',
+            directory: installation.installDir,
+            release: installation.releaseName,
+            record,
+          }, { summary: `Installed MID Server '${installation.name}' and verified it is Up` });
+        }),
+      })
+      .command({
+        command: 'remove <identifier>',
+        aliases: ['delete'],
+        describe: 'Remove a MID Server record',
+        builder: (b) => b.option('force', { type: 'boolean', default: false, describe: 'Skip confirmation' }),
+        handler: wrap(async (argv, app) => {
+          const record = await resolveMidServer(app.sdk, argv.identifier);
+          const sysId = unwrapSysId(record);
+          const name = getStringField(record, 'name') || argv.identifier;
+          await confirmDelete(app, argv, `Remove MID Server '${name}'`);
+          await app.sdk.delete(AGENT_TABLE, sysId);
+          app.ok({ name, sys_id: sysId, deleted: true }, { summary: `Removed MID Server '${name}'` });
+        }),
+      })
+      .command({
+        command: 'execute <identifier>',
+        describe: 'Execute a shell command through a MID Server',
+        builder: (b) => b
+          .option('command', { alias: 'c', type: 'string', demandOption: true, describe: 'Command line to execute on the MID Server host' })
+          .option('timeout', { type: 'number', default: DEFAULT_TIMEOUT, describe: 'Response timeout in milliseconds' })
+          .option('interval', { type: 'number', default: DEFAULT_INTERVAL, describe: 'Polling interval in milliseconds' }),
+        handler: wrap(async (argv, app) => {
+          const record = await resolveMidServer(app.sdk, argv.identifier);
+          assertMidServerUp(record);
+          const agent = agentName(record);
+          const output = await app.sdk.create(QUEUE_TABLE, {
+            agent,
+            topic: 'Command',
+            queue: 'output',
+            name: argv.command,
+            payload: buildCommandPayload(argv.command),
+          });
+          const outputSysId = unwrapSysId(output);
+          if (!outputSysId) throw new Error('ServiceNow did not return the ECC Queue sys_id for the command');
+          const response = await waitForCommandResult(app.sdk, outputSysId, Math.max(1, argv.timeout), Math.max(250, argv.interval));
+          const responseError = getStringField(response, 'error');
+          if (responseError) throw new Error(`MID Server command failed: ${responseError}`);
+          const result = parseCommandResult(queueValue(response.payload));
+          app.ok({
+            mid_server: getStringField(record, 'name'),
+            command: argv.command,
+            output: { sys_id: outputSysId, ...output },
+            response: { ...response, ...result },
+          }, { summary: `Executed command on MID Server '${getStringField(record, 'name')}'` });
+        }),
+      }),
+    handler: () => {
+      console.log('Manage ServiceNow MID Servers and execute commands through them.');
+      console.log('');
+      console.log('Available subcommands:');
+      console.log('  list                         List MID Servers');
+      console.log('  show <name_or_sys_id>        Show a MID Server');
+      console.log('  add --name <name>             Create a MID Server record');
+      console.log('  remove <name_or_sys_id>       Remove a MID Server record');
+      console.log('  execute <name_or_sys_id>      Execute a shell command');
+      console.log('');
+      console.log('Run "jsn midservers <command> --help" for details.');
+    },
+  };
+}
+
+export { waitForCommandResult };

package/src/midserver-install.js

@@ -0,0 +1,134 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { execFileSync } from 'node:child_process';
+
+const INSTALL_HOST = 'install.service-now.com';
+
+function defaultRun(command, args, options = {}) {
+  return execFileSync(command, args, {
+    cwd: options.cwd,
+    env: { ...process.env, ...(options.env || {}) },
+    encoding: 'utf8',
+    stdio: options.stdio || 'inherit',
+  });
+}
+
+function assertSafePart(value, label) {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(value)) {
+    throw new Error(`${label} may contain only letters, numbers, dots, underscores, and dashes`);
+  }
+}
+
+export function normalizeMidName(name) {
+  const shortName = String(name || '').replace(/^mid\.server\./, '');
+  assertSafePart(shortName, 'MID Server name');
+  return shortName;
+}
+
+export function buildMidRecipeUrl(releaseName) {
+  const match = String(releaseName).match(/(\d{4})-(\d{2})-(\d{2})|(\d{2})-(\d{2})-(\d{4})/);
+  if (!match) throw new Error(`MID release name has no build date: ${releaseName}`);
+  const year = match[1] || match[6];
+  const month = match[2] || match[4];
+  const day = match[3] || match[5];
+  const filename = `mid-linux-container-recipe.${releaseName}.linux.x86-64.zip`;
+  return `https://${INSTALL_HOST}/glide/distribution/builds/package/app-signed/mid-linux-container-recipe/${year}/${month}/${day}/${filename}`;
+}
+
+export async function validateMidCredentials(instanceURL, username, password, fetchImpl = fetch) {
+  if (!username || !password) throw new Error('MID Server username and password are required');
+  const endpoint = `${String(instanceURL).replace(/\/$/, '')}/api/now/table/sys_properties?sysparm_query=name=mid.version&sysparm_fields=value&sysparm_limit=1`;
+  let response;
+  try {
+    response = await fetchImpl(endpoint, {
+      headers: {
+        Accept: 'application/json',
+        Authorization: `Basic ${Buffer.from(`${username}:${password}`).toString('base64')}`,
+      },
+    });
+  } catch {
+    throw new Error('Could not reach the ServiceNow instance to validate the MID Server credentials');
+  }
+  if (response.status === 401 || response.status === 403) {
+    throw new Error('The MID Server username or password was rejected by the ServiceNow instance');
+  }
+  if (!response.ok) {
+    throw new Error(`MID Server credential validation failed with HTTP ${response.status}`);
+  }
+  const body = await response.json();
+  const releaseName = body?.result?.[0]?.value;
+  if (!releaseName) throw new Error('Credential validation succeeded, but the instance returned no mid.version value');
+  return { releaseName };
+}
+
+export function dockerComposeAvailable(run = defaultRun) {
+  try {
+    run('docker', ['info'], { stdio: 'ignore' });
+    run('docker', ['compose', 'version'], { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function composeFile({ serviceName }) {
+  return `services:\n  ${serviceName}:\n    container_name: ${serviceName}\n    image: ${serviceName}:\${MID_RELEASE}\n    restart: unless-stopped\n    volumes:\n      - ./export:/opt/snc_mid_server/agent/export\n    environment:\n      MID_INSTANCE_URL: \${MID_INSTANCE_URL}\n      MID_INSTANCE_USERNAME: \${MID_INSTANCE_USERNAME}\n      MID_INSTANCE_PASSWORD: \${MID_INSTANCE_PASSWORD}\n      MID_SERVER_NAME: \${MID_SERVER_NAME}\n`;
+}
+
+export async function installDockerMidServer({
+  instanceURL,
+  username,
+  password,
+  name,
+  directory,
+  releaseName: suppliedReleaseName,
+  fetchImpl = fetch,
+  run = defaultRun,
+}) {
+  if (!dockerComposeAvailable(run)) {
+    throw new Error('Docker and Docker Compose are required for Docker MID Server installation');
+  }
+  const shortName = normalizeMidName(name);
+  const displayName = `mid.server.${shortName}`;
+  const releaseName = suppliedReleaseName || (await validateMidCredentials(instanceURL, username, password, fetchImpl)).releaseName;
+  const recipeURL = buildMidRecipeUrl(releaseName);
+  const installDir = directory || path.join(os.homedir(), '.local', 'share', 'jsn', 'midservers', shortName);
+  fs.mkdirSync(installDir, { recursive: true, mode: 0o700 });
+  const exportDir = path.join(installDir, 'export');
+  fs.mkdirSync(exportDir, { recursive: true, mode: 0o700 });
+  const workDir = fs.mkdtempSync(path.join(os.tmpdir(), 'jsn-mid-'));
+  const filename = path.basename(recipeURL);
+  const archive = path.join(workDir, filename);
+  const recipeDir = path.join(workDir, 'recipe');
+  try {
+    run('curl', ['-fSL', '--connect-timeout', '10', '--max-time', '300', recipeURL, '-o', archive]);
+    fs.mkdirSync(recipeDir, { recursive: true, mode: 0o700 });
+    run('unzip', ['-q', archive, '-d', recipeDir]);
+    const composePath = path.join(installDir, 'docker-compose.yaml');
+    const serviceName = `jsn_mid_${shortName.replace(/[^A-Za-z0-9_.-]/g, '_')}`;
+    run('docker', ['build', '--tag', `${serviceName}:${releaseName}`, recipeDir]);
+    fs.writeFileSync(composePath, composeFile({ serviceName, instanceURL, displayName }), { mode: 0o600 });
+    const env = {
+      MID_RELEASE: releaseName,
+      MID_INSTANCE_URL: `${String(instanceURL).replace(/\/$/, '')}/`,
+      MID_INSTANCE_USERNAME: username,
+      MID_INSTANCE_PASSWORD: password,
+      MID_SERVER_NAME: displayName,
+    };
+    run('docker', ['compose', '-f', composePath, 'up', '-d'], { cwd: installDir, env });
+    return {
+      name: displayName,
+      releaseName,
+      installDir,
+      composePath,
+      serviceName,
+      rollback: () => run('docker', ['compose', '-f', composePath, 'down'], { cwd: installDir, env }),
+    };
+  } finally {
+    fs.rmSync(workDir, { recursive: true, force: true });
+  }
+}
+
+export { defaultRun };