@jacebenson/jsn 1.0.7 → 2.0.2

package/src/context.js

@@ -0,0 +1,62 @@
+// ServiceNow runtime context: current user, scope, update set
+
+export async function getCurrentUser(sdk) {
+  const params = new URLSearchParams();
+  params.set('sysparm_query', 'user_name=javascript:gs.getUserName()');
+  params.set('sysparm_limit', '1');
+  params.set('sysparm_display_value', 'all');
+  params.set('sysparm_fields', 'sys_id,user_name,name');
+  const records = await sdk.list('sys_user', params);
+  if (records.length === 0) return null;
+  const r = records[0];
+  return {
+    sys_id: r.sys_id?.value || r.sys_id,
+    user_name: r.user_name?.display_value || r.user_name,
+    name: r.name?.display_value || r.name,
+  };
+}
+
+export async function getCurrentApplication(sdk, userSysID) {
+  const params = new URLSearchParams();
+  params.set('sysparm_query', `user=${userSysID}^name=apps.current_app`);
+  params.set('sysparm_limit', '1');
+  params.set('sysparm_fields', 'value');
+  const records = await sdk.list('sys_user_preference', params);
+  if (records.length === 0) return { scope: 'global' };
+  const val = records[0].value?.value || records[0].value;
+  if (!val) return { scope: 'global' };
+
+  // Try to resolve sys_id to scope name
+  try {
+    const app = await sdk.get('sys_scope', val);
+    if (app) return { scope: app.scope || 'global' };
+  } catch {
+    // fallback
+  }
+  try {
+    const app2 = await sdk.get('sys_app', val);
+    if (app2) return { scope: app2.scope || 'global' };
+  } catch {
+    // fallback
+  }
+  return { scope: val };
+}
+
+export async function getCurrentUpdateSet(sdk, userSysID) {
+  const params = new URLSearchParams();
+  params.set('sysparm_query', `user=${userSysID}^name=sys_update_set`);
+  params.set('sysparm_limit', '1');
+  params.set('sysparm_fields', 'value');
+  const records = await sdk.list('sys_user_preference', params);
+  if (records.length === 0) return null;
+  const val = records[0].value?.value || records[0].value;
+  if (!val || val === '-') return { name: 'Default', sys_id: '' };
+
+  try {
+    const us = await sdk.get('sys_update_set', val);
+    if (us) return { name: us.name || val, sys_id: val };
+  } catch {
+    // fallback
+  }
+  return { name: val, sys_id: val };
+}

package/src/errors.js

@@ -0,0 +1,101 @@
+// Structured error types with code, message, and optional hint.
+
+export const CodeUsage = 'usage_error';
+export const CodeNotFound = 'not_found';
+export const CodeAuth = 'auth_error';
+export const CodeForbidden = 'forbidden';
+export const CodeRateLimit = 'rate_limited';
+export const CodeNetwork = 'network_error';
+export const CodeAPI = 'api_error';
+export const CodeAmbiguous = 'ambiguous';
+export const CodeEmptyResult = 'empty_result';
+
+export class AppError extends Error {
+  constructor(code, message, hint = '', status = 0, cause = null) {
+    super(message);
+    this.name = 'AppError';
+    this.code = code;
+    this.hint = hint;
+    this.status = status;
+    this.cause = cause;
+  }
+
+  toString() {
+    if (this.hint) {
+      return `${this.code}: ${this.message}\nHint: ${this.hint}`;
+    }
+    return `${this.code}: ${this.message}`;
+  }
+}
+
+export function errUsage(msg) {
+  return new AppError(CodeUsage, msg);
+}
+
+export function errUsageHint(msg, hint) {
+  return new AppError(CodeUsage, msg, hint);
+}
+
+export function errNotFound(resource, identifier) {
+  return new AppError(
+    CodeNotFound,
+    `${resource} not found: ${identifier}`,
+    `Check the ${resource} exists and you have access to it.`
+  );
+}
+
+export function errNotFoundHint(resource, identifier, hint) {
+  return new AppError(CodeNotFound, `${resource} not found: ${identifier}`, hint);
+}
+
+export function errAuth(msg) {
+  return new AppError(CodeAuth, msg, 'Run: jsn auth login');
+}
+
+export function errForbidden(msg) {
+  return new AppError(CodeForbidden, msg, '', 403);
+}
+
+export function errRateLimit(retryAfter) {
+  return new AppError(
+    CodeRateLimit,
+    `Rate limited. Retry after ${retryAfter} seconds.`,
+    'Wait before retrying, or use pagination for large queries.'
+  );
+}
+
+export function errNetwork(cause) {
+  return new AppError(
+    CodeNetwork,
+    `Network error: ${cause.message || cause}`,
+    'Check your internet connection and instance URL.',
+    0,
+    cause
+  );
+}
+
+export function errAPI(status, msg) {
+  let hint = 'Check the API documentation for this endpoint.';
+  if (status >= 500) {
+    hint = 'The ServiceNow instance may be experiencing issues. Try again later.';
+  }
+  return new AppError(CodeAPI, `API error (status ${status}): ${msg}`, hint, status);
+}
+
+export function errAmbiguous(resource, matches) {
+  return new AppError(
+    CodeAmbiguous,
+    `Multiple ${resource} found matching your query`,
+    `Did you mean one of: ${matches.join(', ')}?`
+  );
+}
+
+export function asError(err) {
+  if (!err) return null;
+  if (err instanceof AppError) return err;
+  return new AppError('unknown', err.message || String(err));
+}
+
+export function isErrorCode(err, code) {
+  return err instanceof AppError && err.code === code;
+}

package/src/help.js

@@ -0,0 +1,85 @@
+// Custom grouped help renderer
+// Mirrors the Go version's custom Cobra help template
+
+const COMMAND_GROUPS = {
+  'CORE COMMANDS': [
+    { name: 'incidents', alias: 'inc', desc: 'Manage incidents' },
+    { name: 'changes', alias: 'chg', desc: 'Manage change requests' },
+    { name: 'requests', alias: 'req', desc: 'Manage service catalog requests' },
+    { name: 'tasks', alias: 'task', desc: 'Manage catalog tasks' },
+    { name: 'tickets', alias: 'ticket', desc: 'Query generic tickets' },
+  ],
+  'DATA & ADMIN': [
+    { name: 'records', desc: 'Generic Table API for any table' },
+    { name: 'users', alias: 'user', desc: 'Manage ServiceNow users' },
+    { name: 'groups', alias: 'group', desc: 'Manage groups' },
+    { name: 'groupmembers', alias: 'gm', desc: 'Manage group memberships' },
+    { name: 'grouproles', alias: 'gr', desc: 'Manage group roles' },
+  ],
+  'DEVELOPMENT': [
+    { name: 'dev', desc: 'Manage development artifacts (flows, includes, rules, ACLs, etc.)' },
+  ],
+  'CONFIGURATION': [
+    { name: 'setup', desc: 'Interactive first-time setup' },
+    { name: 'auth', desc: 'Manage OAuth authentication' },
+    { name: 'profiles', alias: 'profile', desc: 'Manage instance profiles' },
+  ],
+};
+
+const UTILITY_COMMANDS = [
+  { name: 'skill', desc: 'Manage the jsn AI agent skill file (show, fetch, install)' },
+  { name: 'version', desc: 'Show version information (--check for npm updates)' },
+];
+
+function renderGroup(name, commands) {
+  const lines = [`\n${name}`];
+  lines.push('─'.repeat(50));
+  for (const cmd of commands) {
+    const aliasPart = cmd.alias ? ` (${cmd.alias})` : '';
+    const padded = `  jsn ${cmd.name}`.padEnd(22);
+    lines.push(`${padded}${cmd.desc}${aliasPart}`);
+  }
+  return lines.join('\n');
+}
+
+function renderFlags() {
+  return `
+FLAGS
+  --instance    ServiceNow instance URL (e.g., https://dev12345.service-now.com)  [string]
+  -p, --profile Configuration profile to use                                      [string]
+  --format      Output format: auto, json, markdown, styled, quiet                [string]
+  --json        Output in JSON format                                            [boolean]
+  -q, --quiet   Output only data, no envelope                                    [boolean]
+  --styled      Force styled output                                              [boolean]
+  --markdown    Output in Markdown format                                        [boolean]
+  --help        Show help                                                        [boolean]`;
+}
+
+function renderTips() {
+  return `
+TIPS
+  --query is available on every list command (e.g. "incidents list --query priority=1")
+  Use "jsn <command> --help" for details, or "jsn <command> list --help" for list options
+
+LEARN MORE
+  Use "jsn <command> --help" for more information about a command.`;
+}
+
+export function renderHelp() {
+  const sections = Object.entries(COMMAND_GROUPS).map(([name, cmds]) => renderGroup(name, cmds));
+  const utilitySection = renderGroup('UTILITY', UTILITY_COMMANDS);
+
+  return [
+    'Usage: jsn <command> [options]',
+    '',
+    `Command-line interface for ServiceNow`,
+    '',
+    ...sections,
+    '',
+    utilitySection,
+    '',
+    renderFlags(),
+    renderTips(),
+    '',
+  ].join('\n');
+}

package/src/helpers.js

@@ -0,0 +1,182 @@
+// Shared helper utilities
+
+import fs from 'node:fs';
+import search from '@inquirer/search';
+import { isTTY, FormatAuto } from './output.js';
+
+export function getStringField(record, field) {
+  if (!record || typeof record !== 'object') return '';
+  const val = record[field];
+  if (val == null) return '';
+  if (typeof val === 'string') return val;
+  if (typeof val === 'object') {
+    if (val.display_value != null) return String(val.display_value);
+    if (val.value != null) return String(val.value);
+  }
+  return String(val);
+}
+
+export function formatRecordForDisplay(record, columns) {
+  const result = {};
+
+  function extractValue(val) {
+    if (val == null) return '';
+    if (typeof val === 'string') return val;
+    if (typeof val === 'object') {
+      if (val.display_value != null && val.display_value !== '') return String(val.display_value);
+      if (val.value != null) return String(val.value);
+    }
+    return String(val);
+  }
+
+  if (record.sys_id != null) {
+    result.sys_id = extractValue(record.sys_id);
+  }
+
+  for (const col of columns) {
+    if (record[col] != null) {
+      result[col] = extractValue(record[col]);
+    } else {
+      result[col] = '';
+    }
+  }
+  return result;
+}
+
+export function truncateString(str, maxLen) {
+  if (!str || str.length <= maxLen) return str;
+  return str.slice(0, maxLen - 3) + '...';
+}
+
+export function isHexString(str) {
+  return /^[0-9a-fA-F]+$/.test(str);
+}
+
+export function extractProfileName(instanceURL) {
+  let name = instanceURL.replace(/^https?:\/\//, '');
+  name = name.replace(/\.service-now\.com$/, '');
+  name = name.replace(/\.servicenowservices\.com$/, '');
+  return name;
+}
+
+export function buildQuerySuffix(query) {
+  return query ? ` --query "${query}"` : '';
+}
+
+/**
+ * Shared interactive list helper with search-as-you-type.
+ * All list commands that want an interactive TTY picker should use this.
+ *
+ * @param {object} opts
+ * @param {App} opts.app
+ * @param {string} opts.table — ServiceNow table name
+ * @param {string} opts.singular — e.g. "script include", "log entry"
+ * @param {string[]} opts.columns — default display columns
+ * @param {number} opts.limit — max records (default 20)
+ * @param {string} opts.query — optional encoded query
+ * @param {Function} opts.formatLabel — (record) => string for the picker display
+ * @param {string} opts.labelField — field used to match selection (default: 'name')
+ * @returns {Promise<void>|null} null if no selection made or non-interactive
+ */
+export async function interactiveList({ app, table, singular, columns, limit = 20, query = '', formatLabel, labelField = 'name' }) {
+  const effectiveFormat = app.output.getFormat() === FormatAuto ? (isTTY(process.stdout) ? FormatAuto : FormatAuto) : app.output.getFormat();
+  if (effectiveFormat !== FormatAuto || !isTTY(process.stdout) || !isTTY(process.stdin) || query) {
+    return null; // not interactive — caller should fall back to text/table
+  }
+
+  const pickerColumns = ['sys_id', labelField, ...columns.filter(c => c !== labelField && c !== 'sys_id')];
+  const params = new URLSearchParams();
+  params.set('sysparm_limit', String(limit));
+  params.set('sysparm_display_value', 'all');
+  params.set('sysparm_fields', pickerColumns.join(','));
+  params.set('sysparm_query', 'ORDERBYDESCsys_updated_on');
+
+  const records = await app.sdk.list(table, params);
+  if (records.length === 0) return null;
+
+  const choices = records.map(r => ({
+    name: formatLabel ? formatLabel(r) : (getStringField(r, labelField) || getStringField(r, 'sys_id')),
+    value: r,
+  }));
+
+  try {
+    const selected = await search({
+      message: `Select ${vowelArticle(singular)} ${singular}:`,
+      source: async (input) => {
+        if (!input) return choices;
+        const term = input.toLowerCase();
+        return choices.filter(c => c.name.toLowerCase().includes(term));
+      },
+    });
+    return selected; // the record object
+  } catch (err) {
+    if (err.name === 'ExitPromptError' || (err.message && err.message.includes('force closed'))) {
+      return null;
+    }
+    throw err;
+  }
+}
+
+function vowelArticle(word) {
+  const first = word.charAt(0).toLowerCase();
+  return first === 'a' || first === 'e' || first === 'i' || first === 'o' || first === 'u' ? 'an' : 'a';
+}
+
+/**
+ * Parse --data or --data-file into a JSON object.
+ * If --data-file is given, reads the file. Otherwise parses --data directly.
+ * Throws if neither is provided or JSON is invalid.
+ */
+export function parseDataArg(argv) {
+  let raw;
+  if (argv['data-file']) {
+    raw = fs.readFileSync(argv['data-file'], 'utf-8');
+  } else if (argv.data) {
+    raw = argv.data;
+  } else {
+    throw new Error('--data or --data-file is required');
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (e) {
+    throw new Error(`Invalid JSON: ${e.message}\n\nHint: On Windows PowerShell, use --data-file instead of --data to avoid quote mangling.\nRaw value: ${raw.substring(0, 200)}`, { cause: e });
+  }
+}
+
+/**
+ * Translate human-readable type names to ServiceNow item_option_new type IDs.
+ * Maps common names like "date", "select", "multilinetext" to their integer IDs.
+ * Passes through numeric values unchanged.
+ */
+const ITEM_OPTION_TYPE_NAMES = {
+  '1': 1, 'yesno': 1, 'yes/no': 1, 'boolean': 1,
+  '2': 2, 'multilinetext': 2, 'textarea': 2, 'multiline': 2,
+  '3': 3, 'multiplechoice': 3,
+  '4': 4, 'numericscale': 4, 'rating': 4,
+  '5': 5, 'select': 5, 'dropdown': 5, 'choice': 5, 'selectbox': 5,
+  '6': 6, 'string': 6, 'text': 6, 'singlelinetext': 6,
+  '7': 7, 'checkbox': 7, 'check': 7,
+  '8': 8, 'reference': 8, 'lookup': 8,
+  '9': 9, 'date': 9,
+  '10': 10, 'datetime': 10, 'date/time': 10,
+  '11': 11, 'label': 11,
+  '14': 14, 'custom': 14,
+  '18': 18, 'lookupselect': 18, 'lookupselectbox': 18,
+  '20': 20, 'containerstart': 20,
+  '21': 21, 'listcollector': 21,
+  '23': 23, 'html': 23,
+  '26': 26, 'email': 26,
+  '29': 29, 'duration': 29,
+  '31': 31, 'requestedfor': 31,
+  '32': 32, 'richtextlabel': 32, 'richtext': 32,
+};
+
+export function resolveItemOptionType(type) {
+  if (type == null) return 6; // default: Single Line Text
+  if (typeof type === 'number') return type;
+  const lower = String(type).toLowerCase().replace(/[\s_-]/g, '');
+  if (ITEM_OPTION_TYPE_NAMES[lower] != null) return ITEM_OPTION_TYPE_NAMES[lower];
+  const asNum = parseInt(String(type), 10);
+  if (!isNaN(asNum) && asNum > 0 && asNum < 100) return asNum;
+  return 6; // fallback to Single Line Text
+}