@jacebenson/jsn 4.3.13 → 4.4.0

package/src/commands/midservers.js

@@ -1,8 +1,13 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
-import { input, password as passwordPrompt, select } from '../prompts.js';
+import { input, password as passwordPrompt, select, confirm } from '../prompts.js';
 import { confirmDelete, formatRecordForDisplay, getStringField, interactiveList, canPrompt, assertSafeExactMatch } from '../helpers.js';
+import { AppError, CodeConfirmationRequired } from '../errors.js';
+import { prepareRemoteMidServer, installRemoteMidServer, startRemoteMidServer, stopRemoteMidServer, logsRemoteMidServer, followRemoteMidServer, removeRemoteMidServer } from '../midserver-remote.js';
+import { prepareWindowsRemoteMidServer, installWindowsRemoteMidServer, startWindowsRemoteMidServer, stopWindowsRemoteMidServer, logsWindowsRemoteMidServer, removeWindowsRemoteMidServer } from '../midserver-windows-remote.js';
+import { prepareLinuxRemoteMidServer, installLinuxRemoteMidServer, startLinuxRemoteMidServer, stopLinuxRemoteMidServer, logsLinuxRemoteMidServer, removeLinuxRemoteMidServer } from '../midserver-linux-remote.js';
+import { downloadRemoteMidRecipe } from '../midserver-remote-recipe.js';
 import { FormatAuto } from '../output.js';
 import { declareCapabilities } from '../capabilities.js';
 import { resolveRecord, unwrapSysId } from '../resolve-record.js';
@@ -15,7 +20,7 @@ const LIST_FIELDS = ['sys_id', 'name', 'status', 'host_name', 'ip_address', 'ver
 const DEFAULT_TIMEOUT = 120000;
 const DEFAULT_INTERVAL = 2000;
 
-declareCapabilities('midservers', { mutationSubcommands: ['add', 'remove', 'execute', 'start', 'stop'] });
+declareCapabilities('midservers', { mutationSubcommands: ['add', 'remove', 'execute', 'start', 'stop', 'validate'] });
 
 function agentName(record) {
   const name = getStringField(record, 'name');
@@ -274,6 +279,13 @@ export function assertMidServerReady(record) {
 }
 
 async function promptMidCredentials(app, argv) {
+  if (argv.passwordStdin) {
+    if (!argv.username) throw new Error('--password-stdin requires --username');
+    const password = fs.readFileSync(0, 'utf8').replace(/\r?\n$/, '');
+    if (!password || Buffer.byteLength(password) > 65536 || password.includes('\0')) throw new Error('Invalid password input');
+    const validation = await validateMidCredentials(app.getEffectiveInstance(), argv.username, password);
+    return { username: argv.username, password, releaseName: validation.releaseName };
+  }
   if (!canPrompt()) throw new Error('MID Server installation is interactive. Run it from a terminal.');
   let username = argv.username || '';
   while (true) {
@@ -344,7 +356,31 @@ function removeLocalMidServer(instanceURL, name, directory) {
   return true;
 }
 
+function remoteDirectory(app, argv, name) {
+  const directory = argv.directory || midInstallDirectory(app.getEffectiveInstance(), name);
+  const file = ['.jsn-mid-windows-remote.json', '.jsn-mid-linux-remote.json', '.jsn-mid-remote.json'].find(name => fs.existsSync(path.join(directory, name)));
+  if (!file) throw new Error('No owned remote MID metadata found');
+  const metadata = JSON.parse(fs.readFileSync(path.join(directory, file), 'utf8'));
+  if (metadata.target !== argv.ssh || metadata.instanceURL !== app.getEffectiveInstance().replace(/\/$/, '') || metadata.name !== name) {
+    throw new Error('Remote MID target, instance or name does not match owned local metadata');
+  }
+  return directory;
+}
+
+function nativeRemote(directory) {
+  if (fs.existsSync(path.join(directory, '.jsn-mid-windows-remote.json'))) return { start: startWindowsRemoteMidServer, stop: stopWindowsRemoteMidServer, logs: logsWindowsRemoteMidServer, remove: removeWindowsRemoteMidServer };
+  if (fs.existsSync(path.join(directory, '.jsn-mid-linux-remote.json'))) return { start: startLinuxRemoteMidServer, stop: stopLinuxRemoteMidServer, logs: logsLinuxRemoteMidServer, remove: removeLinuxRemoteMidServer };
+  return null;
+}
+
 async function showMidServerLogs(app, identifier, argv) {
+  if (argv.ssh) {
+    const directory = remoteDirectory(app, argv, identifier);
+    if (argv.follow && nativeRemote(directory)) throw new Error('Remote native logs currently support bounded --tail only');
+    if (argv.follow) return followRemoteMidServer({ directory, tail: argv.tail });
+    const text = (nativeRemote(directory)?.logs || logsRemoteMidServer)({ directory, tail: argv.tail });
+    return app.ok({ target: argv.ssh, text, _formatted: text }, { summary: 'Remote MID logs' });
+  }
   const installDir = argv.directory || midInstallDirectory(app.getEffectiveInstance(), identifier);
   const direct = readDirectInstallation(app.getEffectiveInstance(), identifier, argv.directory);
   if (direct) {
@@ -420,7 +456,8 @@ export function midserversCmd(wrap) {
         builder: (b) => b
           .option('tail', { type: 'number', default: 100, describe: 'Number of log lines' })
           .option('follow', { type: 'boolean', default: false, describe: 'Follow the logs' })
-          .option('directory', { type: 'string', describe: 'Local installation directory override' }),
+          .option('directory', { type: 'string', describe: 'Local installation metadata directory override' })
+          .option('ssh', { type: 'string', describe: 'Configured SSH alias for the remote MID target' }),
         handler: wrap(async (argv, app) => {
           await showMidServerLogs(app, argv.identifier, argv);
         }),
@@ -431,16 +468,19 @@ export function midserversCmd(wrap) {
         builder: (b) => b
           .option('tail', { type: 'number', default: 100, describe: 'Number of log lines' })
           .option('follow', { type: 'boolean', default: false, describe: 'Follow the logs' })
-          .option('directory', { type: 'string', describe: 'Local installation directory override' }),
+          .option('directory', { type: 'string', describe: 'Local installation metadata directory override' })
+          .option('ssh', { type: 'string', describe: 'Configured SSH alias for the remote MID target' }),
         handler: wrap(async (argv, app) => {
           await showMidServerLogs(app, argv.identifier, argv);
         }),
       })
       .command({
         command: 'start <identifier>',
-        describe: 'Start an owned direct MID (Windows: foreground console, no service)',
-        builder: b => b.option('directory', { type: 'string', describe: 'Installation directory override' }),
+        describe: 'Start an owned MID locally or over SSH (remote Windows uses a service)',
+        builder: b => b.option('directory', { type: 'string', describe: 'Installation directory override' })
+          .option('ssh', { type: 'string', describe: 'Configured SSH alias for the remote MID target' }),
         handler: wrap(async (argv, app) => {
+          if (argv.ssh) { const directory = remoteDirectory(app, argv, argv.identifier); return app.ok((nativeRemote(directory)?.start || startRemoteMidServer)({ directory }), { summary: 'Remote MID start command completed' }); }
           const metadata = readDirectInstallation(app.getEffectiveInstance(), argv.identifier, argv.directory);
           if (!metadata) throw new Error('No owned direct MID installation found');
           if (metadata.state !== 'prepared') throw new Error('MID is already started or has an uncertain runtime state; stop it first');
@@ -450,9 +490,11 @@ export function midserversCmd(wrap) {
       })
       .command({
         command: 'stop <identifier>',
-        describe: 'Stop an owned Linux direct MID; Windows console uses Ctrl+C',
-        builder: b => b.option('directory', { type: 'string', describe: 'Installation directory override' }),
+        describe: 'Stop an owned MID locally or over SSH (local Windows console uses Ctrl+C)',
+        builder: b => b.option('directory', { type: 'string', describe: 'Installation directory override' })
+          .option('ssh', { type: 'string', describe: 'Configured SSH alias for the remote MID target' }),
         handler: wrap(async (argv, app) => {
+          if (argv.ssh) { const directory = remoteDirectory(app, argv, argv.identifier); return app.ok((nativeRemote(directory)?.stop || stopRemoteMidServer)({ directory }), { summary: 'Remote MID stop command completed' }); }
           const metadata = readDirectInstallation(app.getEffectiveInstance(), argv.identifier, argv.directory);
           if (!metadata) throw new Error('No owned direct MID installation found');
           app.ok(runDirectInstallation(metadata, 'stop'), { summary: 'Owned native MID stop command completed' });
@@ -463,13 +505,45 @@ export function midserversCmd(wrap) {
         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('username', { type: 'string', describe: 'MID Server username' })
+          .option('password-stdin', { type: 'boolean', describe: 'Read MID password from stdin instead of a terminal prompt' })
+          .option('ssh', { type: 'string', describe: 'Install MID on a configured SSH target (Docker, native Windows service or Linux background process)' })
+          .option('native-platform', { type: 'string', choices: ['windows', 'linux'], default: 'windows', describe: 'Remote direct ZIP platform (Linux uses a user background process and needs Python 3)' })
           .option('install-method', { type: 'string', choices: ['docker', 'direct'], describe: 'Installation method (prompted when omitted)' })
           .option('directory', { type: 'string', describe: 'Installation directory (must not exist for direct ZIP)' })
           .option('wait-timeout', { type: 'number', default: 300000, 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();
+          if (argv.ssh) {
+            if (!argv.name) throw new Error('Remote installation requires --name');
+            const name = normalizeMidName(argv.name);
+            const existing = await app.sdk.list(AGENT_TABLE, new URLSearchParams({ sysparm_query: `name=${name}`, sysparm_limit: '1', sysparm_fields: 'sys_id' }));
+            if (existing.length) throw new Error('MID name already exists; refusing to adopt an existing MID');
+            const credentials = await promptMidCredentials(app, argv);
+            const directory = argv.directory || midInstallDirectory(app.getEffectiveInstance(), name);
+            fs.mkdirSync(path.dirname(directory), { recursive: true, mode: 0o700 });
+            const native = (argv.installMethod || argv['install-method']) === 'direct';
+            let installation;
+            if (native) {
+              const linux = argv.nativePlatform === 'linux';
+              const prepare = linux ? prepareLinuxRemoteMidServer : prepareWindowsRemoteMidServer;
+              const install = linux ? installLinuxRemoteMidServer : installWindowsRemoteMidServer;
+              const start = linux ? startLinuxRemoteMidServer : startWindowsRemoteMidServer;
+              prepare({ target: argv.ssh, instanceURL: app.getEffectiveInstance(), name, directory });
+              install({ directory, releaseName: credentials.releaseName, username: credentials.username, password: credentials.password });
+              installation = start({ directory });
+            } else {
+              prepareRemoteMidServer({ target: argv.ssh, instanceURL: app.getEffectiveInstance(), name, directory });
+              const context = await downloadRemoteMidRecipe(credentials.releaseName);
+              installation = installRemoteMidServer({ directory, context, username: credentials.username, password: credentials.password });
+            }
+            const kind = native ? (argv.nativePlatform === 'linux' ? 'remote-linux-background' : 'remote-windows-service') : 'remote-docker';
+            let record;
+            try { record = await waitForMidServerUp(app, name, Math.max(1, argv.waitTimeout), Math.max(500, argv.waitInterval)); }
+            catch { return app.ok({ installation: kind, target: argv.ssh, directory, name, registration: 'pending' }, { summary: 'Remote MID started; registration is pending. Runtime and ownership metadata retained for logs or explicit teardown.' }); }
+            return app.ok({ installation: kind, target: argv.ssh, directory, name, registration: 'up', validated: queueValue(record.validated) === 'true', record, runtime_state: installation.state }, { summary: 'Remote MID is Up; validation is a separate explicit operation' });
+          }
           const credentials = await promptMidCredentials(app, argv);
           const name = argv.name || (await input({
             message: 'MID Server name:',
@@ -580,8 +654,19 @@ export function midserversCmd(wrap) {
         aliases: ['delete'],
         describe: 'Remove a MID Server record (interactive when no identifier is given)',
         builder: (b) => b.option('force', { type: 'boolean', default: false, describe: 'Skip confirmation' })
-          .option('directory', { type: 'string', describe: 'Local installation directory override' }),
+          .option('directory', { type: 'string', describe: 'Local installation metadata directory override' })
+          .option('ssh', { type: 'string', describe: 'Configured SSH alias for the remote MID target' }),
         handler: wrap(async (argv, app) => {
+          if (argv.ssh) {
+            if (!argv.identifier) throw new Error('Remote removal requires the owned MID name');
+            const directory = remoteDirectory(app, argv, argv.identifier);
+            await confirmDelete(app, argv, `Remove owned MID '${argv.identifier}' from SSH target '${argv.ssh}' and delete its MID record`);
+            const removed = (nativeRemote(directory)?.remove || removeRemoteMidServer)({ directory });
+            const records = await app.sdk.list(AGENT_TABLE, new URLSearchParams({ sysparm_query: `name=${argv.identifier}`, sysparm_limit: '2', sysparm_fields: 'sys_id,name' }));
+            if (records.length > 1) throw new Error('Remote runtime removed; multiple MID records match. Inspect records before deleting any.');
+            if (records.length) await app.sdk.delete(AGENT_TABLE, unwrapSysId(records[0]));
+            return app.ok({ name: argv.identifier, target: argv.ssh, remote_runtime_removed: removed.state === 'removed', record_deleted: records.length === 1, metadata_directory: directory }, { summary: 'Owned remote MID runtime removed; nonsecret ownership receipt retained' });
+          }
           let record;
           if (argv.identifier) {
             try {
@@ -621,6 +706,28 @@ export function midserversCmd(wrap) {
           app.ok({ name, sys_id: sysId, deleted: Boolean(record), local_compose_removed: localRemoved && !direct, local_installation_removed: localRemoved, local_installation_type: direct ? 'direct' : 'docker' }, { summary: `Removed MID Server '${name}'${localRemoved ? ' and its owned local runtime' : ''}` });
         }),
       })
+      .command({
+        command: 'validate <identifier>',
+        describe: 'Explicitly trust a MID through the platform Validate action; never writes the validated flag directly',
+        builder: b => b.option('timeout', { type: 'number', default: 300000, describe: 'Validation verification timeout in milliseconds' }),
+        handler: wrap(async (argv, app) => {
+          const record = await resolveMidServer(app.sdk, argv.identifier);
+          assertMidServerUp(record);
+          if (!argv.force) {
+            if (!canPrompt() || app.output.getFormat() !== FormatAuto) throw new AppError(CodeConfirmationRequired, 'MID trust validation requires approval.', 'After approval, rerun with --force.');
+            if (!await confirm({ message: `Trust MID '${getStringField(record, 'name')}' using the platform Validate action?`, default: false })) return;
+          }
+          const cookies = await app.sdk._warmSession(), csrf = await app.sdk._getScriptsPageCSRF(cookies);
+          await app.sdk.rawRequest(`${app.sdk.baseURL}/xmlhttp.do`, { method: 'POST', headers: { Cookie: cookies, 'X-UserToken': csrf }, body: new URLSearchParams({ sysparm_processor: 'MIDServerAjax', sysparm_name: 'validateMID', sysparm_agent: unwrapSysId(record), sysparm_ck: csrf }).toString() });
+          const started = Date.now();
+          while (Date.now() - started < argv.timeout) {
+            const current = await resolveMidServer(app.sdk, argv.identifier);
+            if (queueValue(current.validated) === 'true') return app.ok({ name: getStringField(current, 'name'), validated: true }, { summary: 'MID trust validation verified' });
+            await new Promise(resolve => setTimeout(resolve, 2000));
+          }
+          throw new Error('MID validation was requested but not verified; inspect MID issues before retrying');
+        }),
+      })
       .command({
         command: 'execute [identifier]',
         describe: 'Execute a shell command through a MID Server',

package/src/commands/records.js

@@ -1,10 +1,11 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { formatCommandList, formatRecordForDisplay, buildQuerySuffix, buildRecordPayload, getStringField, interactiveList, resolveFieldsParam, checkDerivedFields, confirmDelete, assertSafeExactMatch, verifyWriteBack } from '../helpers.js';
+import { formatCommandList, formatRecordForDisplay, buildQuerySuffix, buildRecordPayload, getStringField, interactiveList, resolveFieldsParam, checkDerivedFields, confirmDelete, verifyWriteBack } from '../helpers.js';
+import { listRecords, recordListParams, getRecord, createRecord, updateRecord, deleteRecord } from '../records-engine.js';
+import { unwrapSysId } from '../resolve-record.js';
+import { errUsage } from '../errors.js';
 import { declareCapabilities } from '../capabilities.js';
 
 declareCapabilities('records', {
-  mutationSubcommands: ['create', 'update', 'delete', 'bulk', 'attachments add'],
+  mutationSubcommands: ['create', 'update', 'delete', 'bulk'],
 });
 
 const tableDefaultColumns = {
@@ -67,6 +68,15 @@ function getDefaultColumns(table) {
   return tableDefaultColumns[table] || ['sys_id'];
 }
 
+function recordLookup(argv) {
+  const sysId = argv['sys-id'];
+  if ((sysId === undefined) === (argv.identifier === undefined)) throw errUsage('Supply exactly one of --sys-id or --identifier.');
+  if (sysId !== undefined && argv.identifierField && argv.identifierField !== 'sys_id') throw errUsage('--sys-id cannot be combined with a different --identifier-field.');
+  return { table: argv.table, identifier: sysId ?? argv.identifier,
+    identifierField: sysId !== undefined ? 'sys_id' : (argv.identifierField || 'sys_id'),
+    displayValues: argv.displayValues, resource: 'Record' };
+}
+
 export function recordsCmd(wrap) {
   return {
     command: 'records [subcommand]',
@@ -83,7 +93,19 @@ export function recordsCmd(wrap) {
             .option('columns', { alias: ['c', 'fields'], type: 'string', describe: 'Comma-separated columns (e.g. "number,short_description")' })
             .option('limit', { type: 'number', default: 20, describe: 'Max records' })
             .option('offset', { type: 'number', default: 0, describe: 'Offset' })
-            .option('count', { type: 'boolean', default: true, describe: 'Include the total-matching count (use --no-count to opt out)' }),
+            .option('display-values', { type: 'string', choices: ['raw', 'display', 'both'], describe: 'Reference values: raw, display or both' })
+            .option('count', { type: 'boolean', default: true, describe: 'Include the total-matching count (use --no-count to opt out)' })
+            .epilogue([
+              'In an interactive terminal with automatic output, browse a picker (10 visible items).',
+              'Use arrow keys to browse, type to search sys_id on the server, scroll to load more,',
+              'and press Enter to select or Esc to cancel. --sys-id skips the picker.',
+              'Use --json for noninteractive structured output; pipes and explicit formats also skip the picker.',
+              'Example: jsn records list --table incident --query "active=true" --limit 5 --json',
+              'JSON shape (abbreviated): {"ok":true,"data":{"records":[{"sys_id":"...","number":"INC0010001"}]},...}',
+              'Records are at data.records; fields are directly on each record (e.g. record.number).',
+              'Array only: jsn records list --table incident --get data.records',
+              'Discover fields with: jsn columns --table incident',
+            ].join('\n')),
           handler: wrap(async (argv, app) => {
             const table = argv.table;
             const columns = argv.columns ? argv.columns.split(',') : getDefaultColumns(table);
@@ -122,15 +144,10 @@ export function recordsCmd(wrap) {
             }
 
             // Text/table fallback (or sys-id direct lookup)
-            const params = new URLSearchParams();
-            params.set('sysparm_limit', argv['sys-id'] ? '1' : String(argv.limit));
-            params.set('sysparm_offset', String(argv.offset));
-            params.set('sysparm_display_value', 'all');
             const fields = resolveFieldsParam(columns);
-            if (fields) params.set('sysparm_fields', fields);
-            if (query) params.set('sysparm_query', query);
-            const records = await app.sdk.list(table, params);
-            const displayRecords = fields ? records.map(r => formatRecordForDisplay(r, columns)) : records;
+            const params = recordListParams({ limit: argv['sys-id'] ? 1 : argv.limit, offset: argv.offset, fields, query });
+            const records = await listRecords(app.sdk, { table, params, displayValues: argv.displayValues });
+            const displayRecords = fields && !argv.displayValues ? records.map(r => formatRecordForDisplay(r, columns)) : records;
 
             // include_counts: default opt-in on every list. Opt out per-profile
             // (config include_counts:false) or per-invocation (--no-count).
@@ -182,27 +199,23 @@ export function recordsCmd(wrap) {
         })
         .command({
           command: 'get',
-          describe: 'Get a single record by sys_id',
+          describe: 'Get one record by sys_id or an explicit identifier field',
           builder: (y) => y
             .option('table', { type: 'string', demandOption: true, describe: 'Table name' })
-            .option('sys-id', { type: 'string', demandOption: true, describe: 'Record sys_id' })
+            .option('sys-id', { type: 'string', describe: 'Full or unambiguous partial record sys_id (including legacy IDs)' })
+            .option('identifier', { type: 'string', describe: 'Identifier value; use --identifier-field number/name/etc for human identifiers' })
+            .option('identifier-field', { type: 'string', describe: 'Exact identifier field (default sys_id); disambiguates names and legacy sys_ids' })
+            .option('display-values', { type: 'string', choices: ['raw', 'display', 'both'], describe: 'Reference values: raw, display or both' })
             .option('columns', { alias: ['c', 'fields'], type: 'string', describe: 'Comma-separated columns (e.g. "number,short_description")' })
-            .option('attachments', { type: 'boolean', default: false, describe: 'Also list the record\'s attachments' }),
+            .option('attachments', { type: 'boolean', default: false, describe: 'Also list the record\'s attachments' })
+            .epilogue('Exact lookup precedes sys_id prefix, then suffix. Ambiguous matches fail.\nExample: jsn records get --table incident --sys-id <sys_id> --json\nExample: jsn records get --table incident --identifier INC0010001 --identifier-field number --json'),
           handler: wrap(async (argv, app) => {
-            assertSafeExactMatch(argv['sys-id']);
-            const params = new URLSearchParams();
-            params.set('sysparm_query', `sys_id=${argv['sys-id']}`);
-            params.set('sysparm_limit', '1');
-            params.set('sysparm_display_value', 'true');
-            if (argv.columns && argv.columns !== '*') params.set('sysparm_fields', `sys_id,${argv.columns}`);
-            const records = await app.sdk.list(argv.table, params);
-            if (records.length === 0) {
-              throw new Error(`Record not found: ${argv['sys-id']}`);
-            }
-            const record = records[0];
+            const lookup = recordLookup(argv);
+            const fields = argv.columns && argv.columns !== '*' ? argv.columns.split(',') : undefined;
+            const record = await getRecord(app.sdk, { ...lookup, fields, displayValue: 'true' });
             if (argv.attachments) {
               try {
-                const atts = await app.sdk.listAttachments(argv['sys-id']);
+                const atts = await app.sdk.listAttachments(unwrapSysId(record));
                 record._attachments = atts;
               } catch {
                 record._attachments = [];
@@ -232,7 +245,7 @@ export function recordsCmd(wrap) {
             for (const w of warnings) {
               process.stderr.write(`⚠ ${w.hint}\n`);
             }
-            const record = await app.sdk.create(argv.table, recordData);
+            const record = await createRecord(app.sdk, { table: argv.table, data: recordData });
             const sysID = getStringField(record, 'sys_id');
             const mismatches = await verifyWriteBack(app, argv.table, sysID, recordData);
             for (const m of mismatches) {
@@ -249,7 +262,9 @@ export function recordsCmd(wrap) {
           describe: 'Update an existing record',
           builder: (y) => y
             .option('table', { type: 'string', demandOption: true, describe: 'Table name' })
-            .option('sys-id', { type: 'string', demandOption: true, describe: 'Record sys_id' })
+            .option('sys-id', { type: 'string', describe: 'Full or unambiguous partial record sys_id (including legacy IDs)' })
+            .option('identifier', { type: 'string', describe: 'Identifier value; use --identifier-field number/name/etc for human identifiers' })
+            .option('identifier-field', { type: 'string', describe: 'Exact identifier field (default sys_id); disambiguates names and legacy sys_ids' })
             .option('data', { type: 'string', describe: 'JSON fields' })
             .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
             .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin (pipe-friendly)' })
@@ -261,8 +276,10 @@ export function recordsCmd(wrap) {
             for (const w of warnings) {
               process.stderr.write(`⚠ ${w.hint}\n`);
             }
-            const record = await app.sdk.update(argv.table, argv['sys-id'], recordData);
-            const mismatches = await verifyWriteBack(app, argv.table, argv['sys-id'], recordData);
+            const lookup = recordLookup(argv);
+            const resolved = await getRecord(app.sdk, lookup);
+            const record = await updateRecord(app.sdk, { table: argv.table, record: resolved, data: recordData });
+            const mismatches = await verifyWriteBack(app, argv.table, unwrapSysId(resolved), recordData);
             for (const m of mismatches) {
               process.stderr.write(`⚠ field "${m.field}" was not persisted (sent: "${m.sent}", got: "${m.got}")\n`);
             }
@@ -277,82 +294,17 @@ export function recordsCmd(wrap) {
           describe: 'Delete a record',
           builder: (y) => y
             .option('table', { type: 'string', demandOption: true, describe: 'Table name' })
-            .option('sys-id', { type: 'string', demandOption: true, describe: 'Record sys_id' })
+            .option('sys-id', { type: 'string', describe: 'Full or unambiguous partial record sys_id (including legacy IDs)' })
+            .option('identifier', { type: 'string', describe: 'Identifier value; use --identifier-field number/name/etc for human identifiers' })
+            .option('identifier-field', { type: 'string', describe: 'Exact identifier field (default sys_id); disambiguates names and legacy sys_ids' })
             .option('force', { type: 'boolean', default: false, describe: 'Skip confirmation' }),
           handler: wrap(async (argv, app) => {
-            await confirmDelete(app, argv, `Delete record from ${argv.table} (${argv['sys-id']})`);
-            await app.sdk.delete(argv.table, argv['sys-id']);
-            app.ok({ message: 'Record deleted', table: argv.table, sys_id: argv['sys-id'] }, { summary: `Deleted record from ${argv.table}` });
+            const lookup = recordLookup(argv);
+            await confirmDelete(app, argv, `Delete record from ${argv.table} (${lookup.identifier})`);
+            const sysID = await deleteRecord(app.sdk, lookup);
+            app.ok({ message: 'Record deleted', table: argv.table, sys_id: sysID }, { summary: `Deleted record from ${argv.table}` });
           }),
         })
-        .command({
-          command: 'attachments',
-          describe: 'Work with attachments on a record',
-          builder: (y) => y
-            .command({
-              command: 'list',
-              describe: 'List attachments on a record',
-              builder: (yy) => yy
-                .option('sys-id', { alias: 's', type: 'string', demandOption: true, describe: 'Parent record sys_id' })
-                .option('table', { type: 'string', describe: 'Parent table name (context only)' }),
-              handler: wrap(async (argv, app) => {
-                app.requireInstance();
-                const attachments = await app.sdk.listAttachments(argv['sys-id']);
-                app.ok({
-                  sys_id: argv['sys-id'],
-                  table: argv.table || '',
-                  count: attachments.length,
-                  attachments,
-                  context: { instance_url: app.getEffectiveInstance() },
-                }, { summary: `${attachments.length} attachment(s) on record ${argv['sys-id']}` });
-              }),
-            })
-            .command({
-              command: 'get <attachment-id>',
-              describe: 'Download an attachment to a local file',
-              builder: (yy) => yy
-                .positional('attachment-id', { describe: 'Attachment sys_id', type: 'string' })
-                .option('sys-id', { alias: 's', type: 'string', demandOption: true, describe: 'Parent record sys_id (used to resolve the file name)' })
-                .option('out', { alias: 'o', type: 'string', describe: 'Output file path (default: attachment file name in cwd)' }),
-              handler: wrap(async (argv, app) => {
-                app.requireInstance();
-                const buf = await app.sdk.getAttachment(argv['attachment-id']);
-                let name = argv.out;
-                if (!name) {
-                  // Best-effort: derive the file name from the attachment row.
-                  let fileName = `${argv['attachment-id']}.bin`;
-                  try {
-                    const rows = await app.sdk.listAttachments(argv['sys-id']);
-                    const hit = (rows || []).find((a) => getStringField(a, 'sys_id') === argv['attachment-id']);
-                    const fn = getStringField(hit, 'file_name');
-                    if (fn) fileName = fn;
-                  } catch { /* keep default */ }
-                  name = fileName;
-                }
-                await fs.promises.writeFile(name, buf);
-                app.ok({ sys_id: argv['attachment-id'], out: name, bytes: buf.length }, { summary: `Wrote ${buf.length} bytes to ${name}` });
-              }),
-            })
-            .command({
-              command: 'add <file>',
-              describe: 'Upload a file as a new attachment on a record (mutation)',
-              builder: (yy) => yy
-                .positional('file', { describe: 'Local file path to upload', type: 'string' })
-                .option('sys-id', { alias: 's', type: 'string', demandOption: true, describe: 'Parent record sys_id' })
-                .option('table', { type: 'string', demandOption: true, describe: 'Parent table for the record (e.g. incident)' })
-                .option('name', { type: 'string', describe: 'Display file name (default: basename of --file)' })
-                .option('force', { type: 'boolean', default: false, describe: 'Skip confirmation' }),
-              handler: wrap(async (argv, app) => {
-                app.requireInstance();
-                await confirmDelete(app, argv, `Upload "${argv.file}" as an attachment on ${argv.table} ${argv['sys-id']}?`);
-                const content = await fs.promises.readFile(argv.file);
-                const fileName = argv.name || path.basename(argv.file);
-                const created = await app.sdk.addAttachment(argv.table, argv['sys-id'], content, fileName);
-                app.ok({ sys_id: created?.sys_id, file_name: fileName, table: argv.table, recordsys_id: argv['sys-id'] }, { summary: `Attached ${fileName}` });
-              }),
-            })
-            .demandCommand(1, 'Specify an attachment action: list, get, or add'),
-        })
         .command({
           command: 'aggregate',
           describe: 'Run ServiceNow Stats API aggregation with optional grouping',
@@ -360,6 +312,7 @@ export function recordsCmd(wrap) {
             .option('table', { type: 'string', demandOption: true, describe: 'Table name' })
             .option('query', { type: 'string', describe: 'Encoded query to constrain the aggregation' })
             .option('group-by', { type: 'string', describe: 'Comma-separated fields to group by' })
+            .option('display-values', { type: 'string', choices: ['raw', 'display', 'both'], describe: 'Reference values: raw, display or both' })
             .option('count', { type: 'boolean', default: true, describe: 'Include record counts' })
             .option('avg-fields', { type: 'string', describe: 'Comma-separated fields to average' })
             .option('sum-fields', { type: 'string', describe: 'Comma-separated fields to sum' })

package/src/commands/requests.js

@@ -1,11 +1,12 @@
-import { buildTicketCommands } from './_ticket.js';
-import { getStringField, assertSafeExactMatch } from '../helpers.js';
+import { enrichRelatedLists, relatedListOptions } from '../related-lists.js';
+import { getRecord, recordOptions } from '../records-engine.js';
+import { unwrapSysId } from '../resolve-record.js';
+import { buildProfileCommand } from '../record-profiles.js';
 
-const requestDefaultColumns = ['number', 'short_description', 'stage', 'assigned_to'];
 
 export function requestsCmd(wrap) {
   // Get the base command definition from the shared ticket builder
-  const baseCmd = buildTicketCommands('sc_req_item', 'requests', 'req', requestDefaultColumns, {}, null, wrap);
+  const baseCmd = buildProfileCommand('requests', wrap);
 
   // Override the builder to inject our enriched show handler.
   // yargs allows re-registration — the last .command() call wins the slot.
@@ -16,6 +17,7 @@ export function requestsCmd(wrap) {
       command: 'show <number>',
       aliases: ['get'],
       describe: 'Show a specific request with attachments and catalog variables',
+      builder: y => relatedListOptions(recordOptions(y)),
       handler: wrap(enrichedShowHandler),
     });
   };
@@ -25,17 +27,8 @@ export function requestsCmd(wrap) {
 
 async function enrichedShowHandler(argv, app) {
   const number = argv.number;
-  assertSafeExactMatch(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('sc_req_item', params);
-  if (records.length === 0) {
-    throw new Error(`Request not found: ${number}`);
-  }
-  const record = records[0];
-  const sysID = getStringField(record, 'sys_id');
+  const record = await getRecord(app.sdk, { table: 'sc_req_item', identifier: number, matchField: 'number', identifierField: argv.identifierField, displayValues: argv.displayValues, resource: 'Request' });
+  const sysID = unwrapSysId(record);
 
   // Fetch attachments and catalog variables in parallel
   const [attachments, variables] = await Promise.all([
@@ -50,6 +43,7 @@ async function enrichedShowHandler(argv, app) {
     table: 'sc_req_item',
   };
 
+  await enrichRelatedLists(record, { table: 'sc_req_item', argv, app });
   app.ok(record, {
     summary: `Request ${number}`,
     breadcrumbs: [

package/src/commands/rest.js

@@ -2,7 +2,7 @@ import { declareCapabilities } from '../capabilities.js';
 
 // Raw REST passthrough — can hit any endpoint with any method, so the whole
 // command is a mutation surface on read-only profiles.
-declareCapabilities('rest', { mutationSubcommands: [''] });
+declareCapabilities('rest', { mutationSubcommands: [''], mutationContextReadMethods: ['GET', 'HEAD', 'OPTIONS'] });
 
 export function restCmd(wrap) {
   return {
@@ -10,6 +10,10 @@ export function restCmd(wrap) {
     describe: 'Make raw REST API calls',
     builder: (yargs) => {
       return yargs
+        .positional('endpoint', {
+          type: 'string',
+          describe: 'API path, optionally including query parameters; with --table, a record sys_id',
+        })
         .option('method', {
           alias: 'X',
           type: 'string',
@@ -34,7 +38,16 @@ export function restCmd(wrap) {
         .option('query', {
           type: 'string',
           describe: 'Query parameters string',
-        });
+        })
+        .epilogue([
+          'Prefer a specific jsn command or records for normal table operations.',
+          'Raw REST is blocked on read-only profiles for every method, including GET.',
+          'Examples:',
+          '  jsn rest "/api/now/table/incident?sysparm_limit=3" --json',
+          '  jsn rest --table incident --query "sysparm_limit=3" --json',
+          '  jsn rest /stats.do --raw',
+          'Use either query parameters in the endpoint or --query, rather than both.',
+        ].join('\n'));
     },
     handler: wrap(async (argv, app) => {
       const validMethods = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'];