@jacebenson/jsn 0.0.9 → 0.1.0

package/src/commands/version.js

@@ -2,6 +2,9 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+const NPM_PKG = '@jacebenson/jsn';
+const NPM_REGISTRY = `https://registry.npmjs.org/${NPM_PKG}/latest`;
+
 function getVersion() {
   try {
     const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -13,13 +16,66 @@ function getVersion() {
   }
 }
 
+async function checkLatest() {
+  try {
+    const res = await fetch(NPM_REGISTRY);
+    if (!res.ok) return null;
+    const data = await res.json();
+    return data.version;
+  } catch {
+    return null;
+  }
+}
+
 export function versionCmd(wrap) {
   return {
     command: 'version',
     describe: 'Show version information',
-    handler: wrap(async (_argv, app) => {
+    builder: (y) => y
+      .option('check', {
+        alias: 'c',
+        type: 'boolean',
+        describe: 'Check npm registry for newer version',
+      }),
+    handler: wrap(async (argv, app) => {
       const version = getVersion();
-      app.ok({ version }, { summary: `jsn ${version}` });
+
+      if (argv.check) {
+        const latest = await checkLatest();
+        if (!latest) {
+          app.ok({ version }, {
+            summary: `jsn ${version} (could not reach npm registry to check for updates)`,
+            notice: `Run \`npm view ${NPM_PKG}\` directly to check manually`,
+          });
+          return;
+        }
+
+        const isUpToDate = version === latest;
+
+        if (isUpToDate) {
+          app.ok({
+            version,
+            latest,
+            upToDate: true,
+          }, {
+            summary: `jsn ${version} — up to date`,
+          });
+        } else {
+          app.ok({
+            version,
+            latest,
+            upToDate: false,
+            installCmd: `npm install -g ${NPM_PKG}`,
+          }, {
+            summary: `jsn ${version} — newer version ${latest} available`,
+            breadcrumbs: [
+              { action: 'update', cmd: `npm install -g ${NPM_PKG}`, description: `Update jsn from ${version} to ${latest}` },
+            ],
+          });
+        }
+      } else {
+        app.ok({ version }, { summary: `jsn ${version}` });
+      }
     }),
   };
 }

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

@@ -1,5 +1,9 @@
 // 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];
@@ -58,3 +62,83 @@ export function extractProfileName(instanceURL) {
 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 });
+  }
+}

package/src/output.js

@@ -358,6 +358,36 @@ export class OutputWriter {
       this.writer.write('\n');
     }
 
+    // ── Attachments ──
+    if (data._attachments && Array.isArray(data._attachments) && data._attachments.length > 0) {
+      this.writer.write('─ Attachments ─\n');
+      for (const att of data._attachments) {
+        const fileName = getDisplayValue(att.file_name);
+        const createdBy = getDisplayValue(att.sys_created_by);
+        const createdOn = getDisplayValue(att.sys_created_on);
+        this.writer.write(`  ${fileName}  (by ${createdBy}, ${createdOn})\n`);
+      }
+      this.writer.write('\n');
+    }
+
+    // ── Catalog Variables ──
+    if (data._variables && Array.isArray(data._variables) && data._variables.length > 0) {
+      this.writer.write('─ Catalog Variables ─\n');
+      for (const v of data._variables) {
+        const q = v.question || '';
+        const val = v.value || '';
+        if (val.includes('\n')) {
+          this.writer.write(`  ${q}:\n`);
+          for (const line of val.split('\n')) {
+            this.writer.write(`    ${line}\n`);
+          }
+        } else {
+          this.writer.write(`  ${q}:  ${val}\n`);
+        }
+      }
+      this.writer.write('\n');
+    }
+
     if (instanceURL && table) {
       const sysID = getDisplayValue(data.sys_id);
       if (sysID) {

package/src/sdk.js

@@ -79,6 +79,56 @@ export class SDKClient {
     }
   }
 
+  // _fetchWithAuth makes an authenticated fetch and returns the Response object.
+  async _fetchWithAuth(endpoint, opts = {}) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const req = new Request(endpoint, { ...opts, signal: controller.signal });
+      await this._setAuth(req);
+      return await fetch(req);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  // rawRequest is like request() but returns the response text as-is (no JSON parsing).
+  // Used for non-JSON endpoints like sys.scripts.do (returns HTML).
+  async rawRequest(endpoint, opts = {}) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+
+    try {
+      const req = new Request(endpoint, {
+        ...opts,
+        signal: controller.signal,
+      });
+      if (opts.body && typeof opts.body === 'string') {
+        req.headers.set('Content-Type', opts.headers?.['Content-Type'] || 'application/x-www-form-urlencoded');
+      }
+      await this._setAuth(req);
+
+      const resp = await fetch(req);
+      const body = await resp.text();
+
+      if (!resp.ok) {
+        throw errAPI(resp.status, body || resp.statusText);
+      }
+
+      return body;
+    } catch (err) {
+      if (err.name === 'AbortError') {
+        throw errNetwork(new Error('Request timed out'));
+      }
+      if (err.code === 'ECONNREFUSED' || err.code === 'ENOTFOUND' || err.code === 'ETIMEDOUT') {
+        throw errNetwork(err);
+      }
+      throw err;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
   async list(table, params = {}) {
     const query = new URLSearchParams(params).toString();
     const endpoint = `${this.baseURL}/api/now/table/${table}${query ? '?' + query : ''}`;
@@ -115,6 +165,22 @@ export class SDKClient {
     await this.request(endpoint, { method: 'DELETE' });
   }
 
+  async getCurrentUser() {
+    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 this.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,
+    };
+  }
+
   async inspectFlow(identifier) {
     const isSysID = identifier.length === 32 && /^[0-9a-fA-F]+$/.test(identifier);
 
@@ -286,6 +352,198 @@ export class SDKClient {
 
     return 0;
   }
+
+  // ─── Background Script Execution (3-step OAuth session flow) ───
+
+  /**
+   * Execute a background script on the ServiceNow instance via sys.scripts.do.
+   * Uses a 3-step session-establishment flow compatible with OAuth tokens:
+   *  1. Make a REST API call to get session cookies
+   *  2. GET /sys.scripts.do with cookies to extract the CSRF token (sysparm_ck)
+   *  3. POST /sys.scripts.do with the script, CSRF token, and cookies
+   *
+   * @param {string} script - JavaScript code to execute
+   * @returns {Promise<string>} The script's output text
+   */
+  async executeScript(script) {
+    // Step 1: Warm up the session by hitting any REST API — this makes
+    // ServiceNow issue session cookies for subsequent UI page requests.
+    // We capture cookies to forward them (Node.js fetch() has no built-in cookie jar).
+    const cookies = await this._warmSession();
+
+    // Step 2: GET /sys.scripts.do to extract the CSRF token from the HTML form.
+    const csrfToken = await this._getScriptsPageCSRF(cookies);
+
+    // Step 3: POST the script with form data including the CSRF token.
+    const endpoint = `${this.baseURL}/sys.scripts.do`;
+    const formBody = new URLSearchParams();
+    formBody.set('script', script);
+    formBody.set('sysparm_ck', csrfToken);
+    formBody.set('runscript', 'Run script');
+    formBody.set('sys_scope', 'global');
+    formBody.set('record_for_rollback', 'on');
+    formBody.set('quota_managed_transaction', 'on');
+
+    const html = await this.rawRequest(endpoint, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        ...(cookies ? { Cookie: cookies } : {}),
+      },
+      body: formBody.toString(),
+    });
+
+    return this._extractScriptOutput(html);
+  }
+
+  /**
+   * Fetch a record and related data from multiple tables.
+   * @param {string} table - Table to query
+   * @param {URLSearchParams} params - Query params for the main record
+   * @param {Array<{table: string, queryField: string, queryValue: string, fields: string[], displayAs: string}>} related - Related tables to fetch
+   * @returns {Promise<{_record: object, [key: string]: any}>}
+   */
+  async recordWithRelated(table, params, related) {
+    const records = await this.list(table, params);
+    if (records.length === 0) throw new Error('Record not found');
+
+    const result = { _record: records[0] };
+
+    for (const rel of related) {
+      try {
+        const relParams = new URLSearchParams();
+        relParams.set('sysparm_display_value', 'all');
+        relParams.set('sysparm_fields', (rel.fields || []).join(','));
+        relParams.set('sysparm_query', `${rel.queryField}=${rel.queryValue}`);
+        relParams.set('sysparm_limit', '100');
+        result[rel.displayAs] = await this.list(rel.table, relParams);
+      } catch {
+        result[rel.displayAs] = [];
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Fetch attachments for a record.
+   * @param {string} tableName - Table name (e.g. sc_req_item)
+   * @param {string} tableSysID - Sys ID of the record
+   * @returns {Promise<Array>}
+   */
+  async fetchAttachments(tableName, tableSysID) {
+    const params = new URLSearchParams();
+    params.set('sysparm_display_value', 'all');
+    params.set('sysparm_fields', 'sys_id,file_name,sys_created_on,sys_created_by');
+    params.set('sysparm_query', `table_name=${tableName}^table_sys_id=${tableSysID}`);
+    return this.list('sys_attachment', params);
+  }
+
+  /**
+   * Fetch catalog variables for a request item (RITM).
+   * @param {string} ritmSysID - Sys ID of the request item
+   * @returns {Promise<Array<{question: string, value: string}>>}
+   */
+  async fetchCatalogVariables(ritmSysID) {
+    const params = new URLSearchParams();
+    params.set('sysparm_display_value', 'all');
+    params.set('sysparm_fields', 'item_option_new,value');
+    params.set('sysparm_query', `request_item=${ritmSysID}`);
+    params.set('sysparm_limit', '100');
+
+    const optRecords = await this.list('sc_item_option', params);
+    const variables = [];
+
+    for (const opt of optRecords) {
+      let question = '';
+      if (opt.item_option_new && typeof opt.item_option_new === 'object') {
+        question = opt.item_option_new.display_value || '';
+      }
+
+      let value = '';
+      if (opt.value && typeof opt.value === 'object') {
+        value = opt.value.display_value || opt.value.value || '';
+      } else if (typeof opt.value === 'string') {
+        value = opt.value;
+      }
+
+      if (question) {
+        variables.push({ question, value });
+      }
+    }
+
+    return variables;
+  }
+
+  async _warmSession() {
+    try {
+      const endpoint = `${this.baseURL}/api/now/table/sys_user?sysparm_limit=1`;
+      const resp = await this._fetchWithAuth(endpoint, { method: 'GET', headers: { Accept: 'application/json' } });
+      // Extract cookies for subsequent UI page requests
+      const setCookie = resp.headers.getSetCookie?.() || resp.headers.get('set-cookie');
+      if (setCookie) {
+        return Array.isArray(setCookie) ? setCookie.join('; ') : setCookie;
+      }
+      return '';
+    } catch {
+      return '';
+    }
+  }
+
+  async _getScriptsPageCSRF(cookies) {
+    const endpoint = `${this.baseURL}/sys.scripts.do`;
+    const html = await this.rawRequest(endpoint, {
+      method: 'GET',
+      headers: cookies ? { Cookie: cookies } : {},
+    });
+
+    // Extract <input name="sysparm_ck" type="hidden" value="TOKEN"> from HTML
+    const marker = '<input name="sysparm_ck" type="hidden" value="';
+    const idx = html.indexOf(marker);
+    if (idx !== -1) {
+      const start = idx + marker.length;
+      const end = html.indexOf('"', start);
+      if (end !== -1) return html.substring(start, end);
+      const altEnd = html.indexOf('">', start);
+      if (altEnd !== -1) return html.substring(start, altEnd);
+    }
+
+    // Fallback: try without type attribute
+    const altMarker = 'name="sysparm_ck" value="';
+    const altIdx = html.indexOf(altMarker);
+    if (altIdx !== -1) {
+      const start = altIdx + altMarker.length;
+      const end = html.indexOf('"', start);
+      if (end !== -1) return html.substring(start, end);
+    }
+
+    // Not authorized or couldn't extract token
+    if (html.includes('not authorized') || html.includes('login.do')) {
+      throw new Error('Not authorized to access scripts page. Your OAuth token may not support UI sessions. Try the browser: ' + this.baseURL + '/sys.scripts.do');
+    }
+    throw new Error('Could not find CSRF token on scripts page (response: ' + html.substring(0, 200) + ')');
+  }
+
+  _extractScriptOutput(html) {
+    // Convert <BR> and <BR/> to newlines first
+    let out = html.replace(/<BR\s*\/?>/gi, '\n').replace(/<br\s*\/?>/gi, '\n');
+
+    // Find <PRE>...</PRE> content
+    const preMatch = out.match(/<PRE[^>]*>([\s\S]*?)<\/PRE>/i);
+    if (preMatch) {
+      out = preMatch[1];
+    }
+
+    // Strip remaining HTML tags
+    out = out.replace(/<[^>]+>/g, '');
+
+    // Clean up: decode HTML entities, trim lines
+    out = out.replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"');
+
+    // Trim each line and remove empty lines
+    const lines = out.split('\n').map(l => l.trim()).filter(l => l.length > 0);
+    return lines.join('\n');
+  }
 }
 
 function getBoolField(record, field) {