@jacebenson/jsn 0.0.3

package/src/auth.js

@@ -0,0 +1,273 @@
+// OAuth 2.0 with PKCE authentication
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import readline from 'node:readline';
+import { globalConfigDir, normalizeInstanceURL } from './config.js';
+import { errAuth } from './errors.js';
+
+const DEFAULT_OAUTH_CLIENT_ID = '543e5655f77746a28228c6009a599dfb';
+const REDIRECT_URI = '/sdk-oauth.do';
+
+function credentialsPath(instance) {
+  const dir = path.join(globalConfigDir(), 'credentials');
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const filename = Buffer.from(instance).toString('base64url') + '.json';
+  return path.join(dir, filename);
+}
+
+function getOAuthClientID() {
+  return process.env.SERVICENOW_OAUTH_CLIENT_ID || DEFAULT_OAUTH_CLIENT_ID;
+}
+
+function generatePKCE() {
+  const verifier = crypto.randomBytes(32).toString('base64url');
+  const challenge = crypto.createHash('sha256').update(verifier).digest('base64url');
+  const state = crypto.randomBytes(16).toString('base64url');
+  return { code_verifier: verifier, code_challenge: challenge, state };
+}
+
+function buildAuthURL(instanceURL, clientID, pkce) {
+  const u = new URL('/oauth_auth.do', instanceURL);
+  u.searchParams.set('response_type', 'code');
+  u.searchParams.set('client_id', clientID);
+  u.searchParams.set('redirect_uri', REDIRECT_URI);
+  u.searchParams.set('state', pkce.state);
+  u.searchParams.set('code_challenge', pkce.code_challenge);
+  u.searchParams.set('code_challenge_method', 'S256');
+  u.searchParams.set('scope', 'openid');
+  return u.toString();
+}
+
+function loadCredentials(instance) {
+  try {
+    const data = fs.readFileSync(credentialsPath(instance), 'utf-8');
+    return JSON.parse(data);
+  } catch {
+    return null;
+  }
+}
+
+function saveCredentials(instance, creds) {
+  fs.writeFileSync(credentialsPath(instance), JSON.stringify(creds, null, 2), { mode: 0o600 });
+}
+
+function deleteCredentials(instance) {
+  try {
+    fs.unlinkSync(credentialsPath(instance));
+  } catch {
+    // ignore
+  }
+}
+
+function askHidden(promptText) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    const stdin = process.stdin;
+    const stdout = process.stdout;
+
+    if (!stdin.isTTY) {
+    rl.question(promptText, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+    return;
+  }
+
+    stdout.write(promptText);
+
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding('utf-8');
+
+    let input = '';
+    const onData = (key) => {
+      if (key === '\r' || key === '\n') {
+        stdin.removeListener('data', onData);
+        stdin.setRawMode(false);
+        stdin.pause();
+        stdout.write('\n');
+        rl.close();
+        resolve(input);
+      } else if (key === '\u0003') {
+        process.exit();
+      } else if (key === '\u007f') {
+        if (input.length > 0) {
+          input = input.slice(0, -1);
+          stdout.write('\b \b');
+        }
+      } else {
+        input += key;
+        stdout.write('*');
+      }
+    };
+    stdin.on('data', onData);
+  });
+}
+
+export class AuthManager {
+  constructor(configProvider) {
+    this.configProvider = configProvider;
+    this.httpClient = { timeout: 30000 };
+  }
+
+  isAuthenticated() {
+    if (process.env.SERVICENOW_OAUTH_TOKEN) return true;
+    const instance = this.configProvider.getEffectiveInstance();
+    if (!instance) return false;
+    try {
+      this.getCredentialsFor(instance);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  isAuthenticatedFor(instance) {
+    if (!instance) return false;
+    const creds = loadCredentials(instance);
+    if (!creds) return false;
+    if (creds.expires_at && Date.now() >= creds.expires_at * 1000) return false;
+    return !!creds.access_token;
+  }
+
+  async getCredentials() {
+    if (process.env.SERVICENOW_OAUTH_TOKEN) {
+      return { auth_method: 'oauth', access_token: process.env.SERVICENOW_OAUTH_TOKEN };
+    }
+    const instance = this.configProvider.getEffectiveInstance();
+    if (!instance) {
+      throw errAuth('No instance configured');
+    }
+    return this.getCredentialsFor(instance);
+  }
+
+  getCredentialsFor(instance) {
+    const creds = loadCredentials(instance);
+    if (!creds) {
+      throw errAuth(`Not authenticated for ${instance}`);
+    }
+    // Check expiry — refresh if less than 5 minutes remaining
+    if (creds.expires_at && Date.now() >= (creds.expires_at - 300) * 1000) {
+      if (creds.refresh_token) {
+        return this.refreshToken(instance, creds);
+      }
+      throw errAuth('Token expired, please login again');
+    }
+    return creds;
+  }
+
+  async login(instanceURL) {
+    instanceURL = normalizeInstanceURL(instanceURL);
+    const clientID = getOAuthClientID();
+    const pkce = generatePKCE();
+    const authURL = buildAuthURL(instanceURL, clientID, pkce);
+
+    console.log();
+    console.log('Opening browser for OAuth authentication...');
+    console.log('If the browser does not open automatically, visit:');
+    console.log(authURL);
+    console.log();
+
+    // Try to open browser
+    const open = (await import('node:child_process')).spawn;
+    const platform = process.platform;
+    const cmd = platform === 'darwin' ? 'open' : platform === 'win32' ? 'start' : 'xdg-open';
+    try {
+      open(cmd, [authURL], { detached: true, stdio: 'ignore' });
+    } catch {
+      // ignore
+    }
+
+    console.log('After authenticating in the browser, copy the authorization code shown on the page.');
+    console.log('(input is hidden for security — just paste and press Enter)');
+    console.log();
+
+    const authCode = await askHidden('Authorization code (hidden on paste for security): ');
+    const code = authCode.trim();
+    if (!code) {
+      throw errAuth('Authorization code is required');
+    }
+
+    console.log('\nExchanging authorization code for tokens...');
+    const newCreds = await this.exchangeCode(instanceURL, clientID, code, pkce);
+    saveCredentials(instanceURL, newCreds);
+    return newCreds;
+  }
+
+  async exchangeCode(instanceURL, clientID, code, pkce) {
+    const tokenURL = `${instanceURL.replace(/\/$/, '')}/oauth_token.do`;
+    const body = new URLSearchParams();
+    body.set('grant_type', 'authorization_code');
+    body.set('client_id', clientID);
+    body.set('code', code);
+    body.set('redirect_uri', REDIRECT_URI);
+    body.set('code_verifier', pkce.code_verifier);
+
+    const resp = await fetch(tokenURL, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: body.toString(),
+    });
+
+    const text = await resp.text();
+    if (!resp.ok) {
+      throw errAuth(`Token exchange failed (status ${resp.status}): ${text}`);
+    }
+
+    const tokenResp = JSON.parse(text);
+    const expiresAt = tokenResp.expires_in ? Math.floor(Date.now() / 1000) + tokenResp.expires_in : 0;
+    return {
+      auth_method: 'oauth',
+      access_token: tokenResp.access_token,
+      refresh_token: tokenResp.refresh_token,
+      expires_at: expiresAt,
+      created_at: Math.floor(Date.now() / 1000),
+    };
+  }
+
+  async refreshToken(instance, creds) {
+    const tokenURL = `${instance.replace(/\/$/, '')}/oauth_token.do`;
+    const clientID = getOAuthClientID();
+    const body = new URLSearchParams();
+    body.set('grant_type', 'refresh_token');
+    body.set('client_id', clientID);
+    body.set('refresh_token', creds.refresh_token);
+
+    const resp = await fetch(tokenURL, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: body.toString(),
+    });
+
+    if (!resp.ok) {
+      const text = await resp.text();
+      throw errAuth(`Token refresh failed: ${text}`);
+    }
+
+    const tokenResp = await resp.json();
+    const newCreds = {
+      auth_method: 'oauth',
+      access_token: tokenResp.access_token,
+      refresh_token: tokenResp.refresh_token,
+      created_at: Math.floor(Date.now() / 1000),
+    };
+    if (tokenResp.expires_in) {
+      newCreds.expires_at = Math.floor(Date.now() / 1000) + tokenResp.expires_in;
+    }
+    saveCredentials(instance, newCreds);
+    return newCreds;
+  }
+
+  logout(instance) {
+    if (!instance) {
+      throw errAuth('No instance specified');
+    }
+    deleteCredentials(instance);
+  }
+}

package/src/cli.js

@@ -0,0 +1,142 @@
+// Root CLI using yargs
+
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+import process from 'node:process';
+import { loadConfig, getEffectiveInstance } from './config.js';
+import { App } from './app.js';
+
+// Command modules
+import { setupCmd } from './commands/setup.js';
+import { authCmd } from './commands/auth.js';
+import { profilesCmd } from './commands/profiles.js';
+import { recordsCmd } from './commands/records.js';
+import { incidentsCmd } from './commands/incidents.js';
+import { changesCmd } from './commands/changes.js';
+import { requestsCmd } from './commands/requests.js';
+import { tasksCmd } from './commands/tasks.js';
+import { usersCmd } from './commands/users.js';
+import { groupsCmd } from './commands/groups.js';
+import { groupMembersCmd } from './commands/groupmembers.js';
+import { groupRolesCmd } from './commands/grouproles.js';
+import { ticketsCmd } from './commands/tickets.js';
+import { versionCmd } from './commands/version.js';
+import { devCmd } from './commands/dev.js';
+
+function wrap(handler) {
+  return async (argv) => {
+    try {
+      const app = argv.app;
+      if (!app) {
+        process.stderr.write('Error: App context not initialized.\n');
+        process.exit(1);
+      }
+      await handler(argv, app);
+    } catch (err) {
+      const app = argv.app;
+      if (app) {
+        app.err(err);
+      } else {
+        process.stderr.write(`Error: ${err.message || err}\n`);
+      }
+      process.exit(1);
+    }
+  };
+}
+
+export const cli = yargs(hideBin(process.argv))
+  .scriptName('jsn')
+  .usage('Usage: $0 <command> [options]')
+  .option('instance', {
+    describe: 'ServiceNow instance URL (e.g., https://dev12345.service-now.com)',
+    type: 'string',
+    global: true,
+  })
+  .option('profile', {
+    alias: 'p',
+    describe: 'Configuration profile to use',
+    type: 'string',
+    global: true,
+  })
+  .option('format', {
+    describe: 'Output format: auto, json, markdown, styled, quiet',
+    type: 'string',
+    global: true,
+  })
+  .option('json', {
+    describe: 'Output in JSON format',
+    type: 'boolean',
+    global: true,
+  })
+  .option('quiet', {
+    alias: 'q',
+    describe: 'Output only data, no envelope',
+    type: 'boolean',
+    global: true,
+  })
+  .option('styled', {
+    describe: 'Force styled output',
+    type: 'boolean',
+    global: true,
+  })
+  .option('markdown', {
+    describe: 'Output in Markdown format',
+    type: 'boolean',
+    global: true,
+  })
+  .middleware((argv) => {
+    // Determine format from flags
+    let format = 'auto';
+    if (argv.json) format = 'json';
+    else if (argv.quiet) format = 'quiet';
+    else if (argv.styled) format = 'styled';
+    else if (argv.markdown) format = 'markdown';
+    else if (argv.format) format = argv.format;
+
+    const cfg = loadConfig({
+      instance: argv.instance,
+      profile: argv.profile,
+      format,
+    });
+
+    argv.app = new App(cfg);
+
+    // Check auth for non-auth commands
+    const cmd = argv._[0];
+    const skipAuth = ['help', 'version', 'setup', 'auth', undefined].includes(cmd);
+    if (!skipAuth) {
+      const instance = getEffectiveInstance(cfg);
+      if (!argv.app.auth.isAuthenticated() && instance) {
+        process.stderr.write(`\n⚠️  Not authenticated to ${instance}\n\n`);
+        process.stderr.write('To get started, run:\n');
+        process.stderr.write('  jsn setup           # Interactive setup\n');
+        process.stderr.write(`  jsn auth login ${instance}   # Login to instance\n\n`);
+      }
+    }
+
+    // Print context header for interactive terminals
+    if (!['help', 'version', 'completion'].includes(cmd)) {
+      argv.app.printContextHeader();
+    }
+  })
+  .command(setupCmd(wrap))
+  .command(authCmd(wrap))
+  .command(profilesCmd(wrap))
+  .command(recordsCmd(wrap))
+  .command(incidentsCmd(wrap))
+  .command(changesCmd(wrap))
+  .command(requestsCmd(wrap))
+  .command(tasksCmd(wrap))
+  .command(usersCmd(wrap))
+  .command(groupsCmd(wrap))
+  .command(groupMembersCmd(wrap))
+  .command(groupRolesCmd(wrap))
+  .command(ticketsCmd(wrap))
+  .command(devCmd(wrap))
+  .command(versionCmd(wrap))
+  .demandCommand(1, 'You must specify a command')
+  .help('help', 'Show help')
+  .version(false)
+  .strictCommands()
+  .strictOptions(false)
+  .epilogue('LEARN MORE\n  Use "jsn <command> --help" for more information about a command.');

package/src/commands/_ticket.js

@@ -0,0 +1,256 @@
+// Generic command builder for CRUD operations on a ServiceNow table
+// Used by incidents, changes, requests, tasks, and most dev subcommands
+
+import { getStringField, formatRecordForDisplay, buildQuerySuffix } from '../helpers.js';
+import { select } from '@inquirer/prompts';
+import { isTTY, FormatAuto } from '../output.js';
+
+export function buildTicketCommands(table, displayName, alias, defaultColumns, stateMap, iconFn, wrap) {
+  return {
+    command: `${displayName} [subcommand]`,
+    aliases: [table, alias],
+    describe: `Manage ${displayName}`,
+    builder: (yargs) => {
+      return yargs
+        .command({
+          command: 'list',
+          aliases: ['ls'],
+          describe: `List ${table}`,
+          builder: (y) => y
+            .option('query', { type: 'string', describe: 'Encoded query string' })
+            .option('columns', { alias: 'c', type: 'string', describe: 'Comma-separated columns' })
+            .option('limit', { alias: 'l', type: 'number', default: 20, describe: 'Max records' })
+            .option('offset', { alias: 'o', type: 'number', default: 0, describe: 'Offset for pagination' }),
+          handler: wrap(async (argv, app) => {
+            const query = argv.query || '';
+            const columns = argv.columns ? argv.columns.split(',') : defaultColumns;
+            const limit = argv.limit;
+            const offset = argv.offset;
+
+            // Interactive picker in TTY with auto format and no explicit query/offset
+            const isInteractive = isTTY(process.stdout) && isTTY(process.stdin);
+            if (isInteractive && app.output.getFormat() === FormatAuto && !query && offset === 0) {
+              const pickerColumns = ['sys_id', 'number', 'short_description', 'state', 'assigned_to'];
+              const pickerParams = new URLSearchParams();
+              pickerParams.set('sysparm_limit', String(limit));
+              pickerParams.set('sysparm_offset', '0');
+              pickerParams.set('sysparm_display_value', 'all');
+              pickerParams.set('sysparm_fields', pickerColumns.join(','));
+              pickerParams.set('sysparm_query', 'ORDERBYDESCsys_updated_on');
+
+              const pickerRecords = await app.sdk.list(table, pickerParams);
+              if (pickerRecords.length === 0) {
+                app.ok({
+                  table,
+                  count: 0,
+                  columns: pickerColumns,
+                  records: [],
+                  pagination: { limit, offset: 0 },
+                  context: { instance_url: app.getEffectiveInstance() },
+                }, {
+                  summary: `0 ${table}(s)`,
+                  breadcrumbs: [
+                    { action: 'create', cmd: `jsn ${alias} create --description "..."`, description: `Create a new ${displayName}` },
+                  ],
+                });
+                return;
+              }
+
+              const choices = pickerRecords.map((record) => {
+                const number = getStringField(record, 'number');
+                const desc = getStringField(record, 'short_description');
+                const state = getStringField(record, 'state');
+                const assigned = getStringField(record, 'assigned_to');
+                let label = `${number} ${desc} | ${state}`;
+                if (assigned) {
+                  label += ` → ${assigned}`;
+                }
+                return { name: label, value: number };
+              });
+
+              let selectedNumber;
+              try {
+                selectedNumber = await select({
+                  message: `Select a ${displayName.slice(0, -1)}:`,
+                  choices,
+                });
+              } catch (err) {
+                if (err.name === 'ExitPromptError' || (err.message && err.message.includes('force closed'))) {
+                  return;
+                }
+                throw err;
+              }
+
+              if (selectedNumber) {
+                const showParams = new URLSearchParams();
+                showParams.set('sysparm_query', `number=${selectedNumber}`);
+                showParams.set('sysparm_display_value', 'all');
+                showParams.set('sysparm_limit', '1');
+                const showRecords = await app.sdk.list(table, showParams);
+                if (showRecords.length === 0) {
+                  throw new Error(`${displayName} not found: ${selectedNumber}`);
+                }
+                const record = showRecords[0];
+                record._context = {
+                  instance_url: app.getEffectiveInstance(),
+                  table,
+                };
+                app.ok(record, {
+                  summary: `${displayName.charAt(0).toUpperCase() + displayName.slice(1)} ${selectedNumber}`,
+                  breadcrumbs: [
+                    { action: 'update', cmd: `jsn ${alias} update ${selectedNumber} --data '{...}'`, description: `Update this ${displayName}` },
+                    { action: 'list', cmd: `jsn ${alias} list`, description: `Back to all ${table}` },
+                  ],
+                });
+              }
+              return;
+            }
+
+            const params = new URLSearchParams();
+            params.set('sysparm_limit', String(limit));
+            params.set('sysparm_offset', String(offset));
+            params.set('sysparm_display_value', 'all');
+            const fetchColumns = ['sys_id', ...columns];
+            params.set('sysparm_fields', fetchColumns.join(','));
+            const q = query ? query + '^ORDERBYDESCsys_updated_on' : 'ORDERBYDESCsys_updated_on';
+            params.set('sysparm_query', q);
+
+            const records = await app.sdk.list(table, params);
+            const displayRecords = records.map(r => formatRecordForDisplay(r, columns));
+
+            const breadcrumbs = [
+              { action: 'create', cmd: `jsn ${alias} create --description "..."`, description: `Create a new ${displayName}` },
+              { action: 'filter', cmd: `jsn ${alias} list --query "priority=1"`, description: 'Filter: critical only' },
+            ];
+
+            if (records.length === limit) {
+              breadcrumbs.push({
+                action: 'next',
+                cmd: `jsn ${alias} list --limit ${limit} --offset ${offset + limit}${buildQuerySuffix(query)}`,
+                description: `Next page (offset ${offset + limit})`,
+              });
+            }
+            if (offset > 0) {
+              breadcrumbs.push({
+                action: 'prev',
+                cmd: `jsn ${alias} list --limit ${limit} --offset ${Math.max(0, offset - limit)}${buildQuerySuffix(query)}`,
+                description: 'Previous page',
+              });
+            }
+
+            app.ok({
+              table,
+              count: records.length,
+              columns,
+              records: displayRecords,
+              pagination: { limit, offset },
+              context: { instance_url: app.getEffectiveInstance() },
+            }, {
+              summary: `${records.length} ${table}(s)`,
+              breadcrumbs,
+            });
+          }),
+        })
+        .command({
+          command: 'show <number>',
+          aliases: ['get'],
+          describe: `Show a specific ${displayName}`,
+          handler: wrap(async (argv, app) => {
+            const number = argv.number;
+            const params = new URLSearchParams();
+            params.set('sysparm_query', `number=${number}`);
+            params.set('sysparm_display_value', 'all');
+            params.set('sysparm_limit', '1');
+            const records = await app.sdk.list(table, params);
+            if (records.length === 0) {
+              throw new Error(`${displayName} not found: ${number}`);
+            }
+            const record = records[0];
+            record._context = {
+              instance_url: app.getEffectiveInstance(),
+              table,
+            };
+            app.ok(record, {
+              summary: `${displayName.charAt(0).toUpperCase() + displayName.slice(1)} ${number}`,
+              breadcrumbs: [
+                { action: 'update', cmd: `jsn ${alias} update ${number} --data '{...}'`, description: `Update this ${displayName}` },
+                { action: 'list', cmd: `jsn ${alias} list`, description: `Back to all ${table}` },
+              ],
+            });
+          }),
+        })
+        .command({
+          command: 'create',
+          describe: `Create a new ${displayName}`,
+          builder: (y) => y
+            .option('description', { alias: 'd', type: 'string', describe: 'Short description' })
+            .option('priority', { type: 'string', describe: 'Priority (1-5)' })
+            .option('data', { type: 'string', describe: 'JSON data for additional fields' }),
+          handler: wrap(async (argv, app) => {
+            const recordData = {};
+            if (argv.data) {
+              Object.assign(recordData, JSON.parse(argv.data));
+            }
+            if (argv.description) recordData.short_description = argv.description;
+            if (argv.priority) recordData.priority = argv.priority;
+            if (!recordData.short_description) {
+              throw new Error('short_description is required (use --description or --data)');
+            }
+            const record = await app.sdk.create(table, recordData);
+            app.ok(record, {
+              summary: `Created ${displayName} ${getStringField(record, 'number')}`,
+              breadcrumbs: [
+                { action: 'view', cmd: `jsn ${alias} show ${getStringField(record, 'number')}`, description: `View the new ${displayName}` },
+              ],
+            });
+          }),
+        })
+        .command({
+          command: 'update <number>',
+          describe: `Update a ${displayName}`,
+          builder: (y) => y
+            .option('data', { type: 'string', demandOption: true, describe: 'JSON data to update' }),
+          handler: wrap(async (argv, app) => {
+            const number = argv.number;
+            const recordData = JSON.parse(argv.data);
+            const findParams = new URLSearchParams();
+            findParams.set('sysparm_query', `number=${number}`);
+            findParams.set('sysparm_limit', '1');
+            const records = await app.sdk.list(table, findParams);
+            if (records.length === 0) {
+              throw new Error(`${displayName} not found: ${number}`);
+            }
+            const sysID = getStringField(records[0], 'sys_id');
+            const updated = await app.sdk.update(table, sysID, recordData);
+            app.ok(updated, {
+              summary: `Updated ${displayName} ${number}`,
+              breadcrumbs: [
+                { action: 'view', cmd: `jsn ${alias} show ${number}`, description: `View the updated ${displayName}` },
+              ],
+            });
+          }),
+        })
+        .command({
+          command: 'delete <number>',
+          describe: `Delete a ${displayName}`,
+          handler: wrap(async (argv, app) => {
+            const number = argv.number;
+            const findParams = new URLSearchParams();
+            findParams.set('sysparm_query', `number=${number}`);
+            findParams.set('sysparm_limit', '1');
+            const records = await app.sdk.list(table, findParams);
+            if (records.length === 0) {
+              throw new Error(`${displayName} not found: ${number}`);
+            }
+            const sysID = getStringField(records[0], 'sys_id');
+            await app.sdk.delete(table, sysID);
+            app.ok({ number, message: `${displayName.charAt(0).toUpperCase() + displayName.slice(1)} deleted` }, {
+              summary: `Deleted ${displayName} ${number}`,
+            });
+          }),
+        })
+
+    },
+    handler: () => {}, // Handled by subcommands
+  };
+}