@jacebenson/jsn 4.3.7-dev.21 → 4.3.7-dev.23

package/package.json

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

package/src/commands/midservers.js

@@ -1,6 +1,9 @@
-import { confirmDelete, getStringField, parseDataArg } from '../helpers.js';
+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 { detectDocker, installDockerMidServer, validateMidCredentials } from '../midserver-install.js';
 
 const AGENT_TABLE = 'ecc_agent';
 const QUEUE_TABLE = 'ecc_queue';
@@ -87,21 +90,106 @@ async function resolveMidServer(sdk, identifier) {
 }
 
 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: (argv.columns ? [...new Set(['sys_id', ...argv.columns.split(',')])] : LIST_FIELDS).join(','),
-    sysparm_query: argv.query || 'ORDERBYname',
+    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,
-    records,
+    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]',
@@ -132,33 +220,102 @@ export function midserversCmd(wrap) {
       })
       .command({
         command: 'add',
-        describe: 'Create a MID Server record',
+        describe: 'Install and verify a MID Server',
         builder: (b) => b
-          .option('name', { type: 'string', describe: 'MID Server name (without the mid.server. prefix)' })
-          .option('host-name', { type: 'string', describe: 'MID Server host name' })
-          .option('ip-address', { type: 'string', describe: 'MID Server IP address' })
-          .option('data', { type: 'string', describe: 'JSON fields for the ecc_agent record' })
-          .option('data-file', { type: 'string', describe: 'Read JSON fields from a file' }),
+          .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) => {
-          let data = argv.data || argv['data-file'] ? parseDataArg(argv) : {};
-          if (argv.name) data.name = argv.name;
-          if (!data.name) throw new Error('--name or --data with a name is required');
-          data.name = String(data.name).startsWith('mid.server.') ? data.name : `mid.server.${data.name}`;
-          if (argv['host-name']) data.host_name = argv['host-name'];
-          if (argv['ip-address']) data.ip_address = argv['ip-address'];
-          const record = await app.sdk.create(AGENT_TABLE, data);
-          app.ok(record, { summary: `Created MID Server '${getStringField(record, 'name') || data.name}'` });
+          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 dockerStatus = detectDocker();
+          const dockerAvailable = dockerStatus.available;
+          const installMethod = argv['install-method'] || await select({
+            message: dockerAvailable
+              ? 'Docker and Docker Compose are ready. How should the MID Server be installed?'
+              : dockerStatus.installed && dockerStatus.compose
+                ? 'Docker is installed, but this user cannot access the Docker daemon. 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' },
+              ]
+              : dockerStatus.installed && dockerStatus.compose
+                ? [
+                  { name: 'Fix Docker daemon access first', value: 'docker-unavailable' },
+                  { 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 === 'docker-unavailable') throw new Error('Docker is installed, but this user cannot access the Docker daemon. Start Docker and grant this user access to /var/run/docker.sock, then run this command again.');
+          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>',
+        command: 'remove [identifier]',
         aliases: ['delete'],
-        describe: 'Remove a MID Server record',
+        describe: 'Remove a MID Server record (interactive when no identifier is given)',
         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);
+          let record;
+          if (argv.identifier) {
+            record = await resolveMidServer(app.sdk, argv.identifier);
+          } else {
+            if (!canPrompt() || app.output.getFormat() !== FormatAuto) {
+              throw new Error('An identifier is required outside an interactive terminal');
+            }
+            record = await interactiveList({
+              app,
+              table: AGENT_TABLE,
+              singular: 'MID Server',
+              columns: LIST_FIELDS,
+              limit: 50,
+              labelField: 'name',
+              message: 'Select a MID Server to remove',
+              formatLabel: (candidate) => {
+                const name = getStringField(candidate, 'name') || getStringField(candidate, 'sys_id');
+                const status = getStringField(candidate, 'status');
+                return status ? `${name} [${status}]` : name;
+              },
+            });
+            if (!record) return;
+          }
           const sysId = unwrapSysId(record);
-          const name = getStringField(record, 'name') || argv.identifier;
+          const name = getStringField(record, 'name') || argv.identifier || sysId;
           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}'` });
@@ -173,6 +330,7 @@ export function midserversCmd(wrap) {
           .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,

package/src/midserver-install.js

@@ -0,0 +1,137 @@
+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 detectDocker(run = defaultRun) {
+  const status = { installed: false, compose: false, daemon: false, available: false };
+  try { run('docker', ['--version'], { stdio: 'ignore' }); status.installed = true; } catch { return status; }
+  try { run('docker', ['compose', 'version'], { stdio: 'ignore' }); status.compose = true; } catch { return status; }
+  try { run('docker', ['info'], { stdio: 'ignore' }); status.daemon = true; } catch { return status; }
+  status.available = true;
+  return status;
+}
+
+export function dockerComposeAvailable(run = defaultRun) {
+  return detectDocker(run).available;
+}
+
+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 };