@jacebenson/jsn 4.3.12 → 4.3.13-dev.101.1

package/src/commands/records.js

@@ -1,10 +1,11 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { formatCommandList, formatRecordForDisplay, buildQuerySuffix, parseDataArg, 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,16 @@ 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',
+              '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 +141,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).
@@ -142,7 +156,7 @@ export function recordsCmd(wrap) {
             }
 
             const breadcrumbs = [
-              { action: 'create', cmd: `jsn records create --table ${table} --data '{...}'`, description: 'Create a new record' },
+              { action: 'create', cmd: `jsn records create --table ${table} -f name=value`, description: 'Create a new record' },
               { action: 'filter', cmd: `jsn records list --table ${table} --query "priority=1"`, description: 'Filter: priority 1 only' },
               { action: 'columns', cmd: `jsn columns --table ${table}`, description: 'View available columns' },
             ];
@@ -182,27 +196,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 = [];
@@ -221,17 +231,18 @@ export function recordsCmd(wrap) {
           describe: 'Create a new record',
           builder: (y) => y
             .option('table', { type: 'string', demandOption: true, describe: 'Table name' })
-            .option('data', { type: 'string', describe: 'JSON fields (e.g. \'{"state":"2"}\')' })
+            .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)' })
+            .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' })
             .option('strict', { type: 'boolean', default: false, describe: 'Exit non-zero if any supplied field was not persisted (write-back check)' }),
           handler: wrap(async (argv, app) => {
-            const recordData = parseDataArg(argv);
+            const recordData = buildRecordPayload(argv);
             const warnings = checkDerivedFields(argv.table, recordData);
             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) {
@@ -248,19 +259,24 @@ 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('data', { type: 'string', describe: 'JSON fields (e.g. \'{"state":"2"}\')' })
+            .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)' })
+            .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' })
             .option('strict', { type: 'boolean', default: false, describe: 'Exit non-zero if any supplied field was not persisted (write-back check)' }),
           handler: wrap(async (argv, app) => {
-            const recordData = parseDataArg(argv);
+            const recordData = buildRecordPayload(argv);
             const warnings = checkDerivedFields(argv.table, recordData);
             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`);
             }
@@ -275,82 +291,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',
@@ -358,6 +309,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' })
@@ -401,22 +353,15 @@ export function recordsCmd(wrap) {
           builder: (y) => y
             .option('table', { type: 'string', demandOption: true, describe: 'Table name' })
             .option('query', { type: 'string', demandOption: true, describe: 'Encoded query selecting the records to update (e.g. "priority=1^state=1")' })
-            .option('set', { type: 'string', demandOption: true, describe: 'JSON object of fields to set (e.g. \'{"state":"3"}\')' })
+            .option('set', { type: 'string', describe: 'JSON object of fields to set' })
+            .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' })
             .option('dry-run', { type: 'boolean', default: true, describe: 'Preview the count + a sample without mutating (default)' })
             .option('execute', { type: 'boolean', default: false, describe: 'Perform the update after confirmation' })
             .option('limit', { type: 'number', default: 200, describe: 'Max records to update when executing' })
             .option('force', { type: 'boolean', default: false, describe: 'Skip confirmation (with --execute)' }),
           handler: wrap(async (argv, app) => {
             app.requireInstance();
-            let set;
-            try {
-              set = JSON.parse(argv.set);
-            } catch (e) {
-              throw new Error(`Invalid --set JSON: ${e.message}`, { cause: e });
-            }
-            if (!set || typeof set !== 'object' || Array.isArray(set)) {
-              throw new Error('--set must be a JSON object of field=value pairs');
-            }
+            const set = buildRecordPayload({ ...argv, data: argv.set }, { required: true });
             if (!argv['dry-run'] && !argv.execute) {
               argv.execute = true; // explicit --no-dry-run implies execute intent
             }

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,10 +43,11 @@ 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: [
-      { action: 'update', cmd: `jsn req update ${number} --data '{...}'`, description: 'Update this request' },
+      { action: 'update', cmd: `jsn req update ${number} -f state=2`, description: 'Update this request' },
       { action: 'list', cmd: `jsn req list`, description: 'Back to all requests' },
     ],
   });

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'];

package/src/commands/scan.js

@@ -0,0 +1,234 @@
+import { buildRecordPayload, confirmDelete, getStringField, quoteShellArg, verifyWriteBack } from '../helpers.js';
+import { createRecord, updateRecord, deleteRecord } from '../records-engine.js';
+import { unwrapSysId } from '../resolve-record.js';
+import { getCurrentApplication, getCurrentUser } from '../context.js';
+import { declareCapabilities } from '../capabilities.js';
+import { errAPI, errUsage } from '../errors.js';
+import { CHECK_TABLES, active, raw, referenceId, boundedLimit, scanList, resolveScanRecord,
+  validateScanPayload, checkKind, prepareScan, startScan, scanStatus, scanResults, cancelScan } from '../scan.js';
+
+declareCapabilities('scan', { mutationSubcommands: [
+  ...['checks', 'suites'].flatMap(group => ['create', 'update', 'delete', 'activate', 'deactivate'].map(verb => `${group} ${verb}`)),
+  'suites add-check', 'suites remove-check', 'run', 'cancel',
+] });
+
+const hint = (action, cmd, description) => ({ action, cmd, description });
+function report(app, argv, data, options) {
+  const connection = argv.profile ? ` --profile ${quoteShellArg(argv.profile)}`
+    : argv.instance ? ` --instance ${quoteShellArg(argv.instance)}` : '';
+  app.ok(data, { ...options, breadcrumbs: options.breadcrumbs.map(item => ({ ...item, cmd: item.cmd + connection })) });
+}
+const rootHints = () => [hint('checks', 'jsn scan checks list', 'Browse available checks'),
+  hint('suites', 'jsn scan suites list', 'Browse suites'), hint('run', 'jsn scan run --help', 'Choose an explicit scan target')];
+const itemHints = (group, record) => {
+  const id = unwrapSysId(record);
+  return [hint('list', `jsn scan ${group} list`, `Browse ${group}`),
+    hint('show', `jsn scan ${group} show ${id}`, 'Inspect this definition'),
+    hint('update', `jsn scan ${group} update ${id} --data-file ${group === 'checks' ? 'check' : 'suite'}.json`, 'Update selected fields'),
+    hint(active(record) ? 'deactivate' : 'activate', `jsn scan ${group} ${active(record) ? 'deactivate' : 'activate'} ${id}`, 'Change eligibility without starting a scan'),
+    ...(group === 'suites' ? [hint('add-check', `jsn scan suites add-check ${id} --check '<check-id-or-name>'`, 'Add an existing check'),
+      hint('run', `jsn scan run --suite ${id} --update-set '<update-set>'`, 'Run against an explicit update set')] :
+      [hint('suites', 'jsn scan suites list', 'Choose a suite for this check')]),
+    hint('delete', `jsn scan ${group} delete ${id}`, 'Delete this definition after confirmation')];
+};
+
+function executionHints(data) {
+  const id = data.execution_id;
+  return [hint('status', `jsn scan status ${id}`, 'Read execution progress'),
+    hint('results', `jsn scan results ${id}`, 'Inspect findings and recorded check executions'),
+    ...(!data.terminal ? [hint('cancel', `jsn scan cancel ${id}`, 'Request cancellation')] : []),
+    ...(data.reusable_target ? [hint('rerun', `jsn scan run --previous ${id}${data.rerun_full ? ' --full' : ''}`, 'Rerun the previous target with current check definitions')] : []),
+    hint('checks', 'jsn scan checks list', 'Review available checks')];
+}
+
+const payloadOptions = y => y.option('data', { type: 'string', describe: 'JSON fields' })
+  .option('data-file', { type: 'string', describe: 'Read JSON fields from a file (recommended for scripts)' })
+  .option('data-stdin', { type: 'boolean', describe: 'Read JSON fields from stdin' })
+  .option('field', { alias: 'f', type: 'array', describe: 'Set field=value; repeatable' });
+const lookupOptions = y => y.positional('identifier', { type: 'string', describe: 'Unique name or sys_id' });
+
+async function guardScope(app, record) {
+  const scopeId = referenceId(record.sys_scope) || raw(record.sys_scope);
+  if (!scopeId) throw errUsage('The definition scope is unreadable; inspect permissions before changing it.');
+  const user = await getCurrentUser(app.sdk);
+  if (!user) throw errUsage('Could not verify the current scope.');
+  const scope = await getCurrentApplication(app.sdk, user.sys_id, { unknownWhenMissing: true });
+  if (scope.appSysId !== scopeId && scope.scope !== scopeId) {
+    throw errUsage(`Select the definition scope before changing it: jsn scopes set ${quoteShellArg(scopeId)}`);
+  }
+}
+
+async function verify(app, table, id, data) {
+  if (!id) throw errAPI(200, 'The write returned no sys_id. Inspect the instance before retrying.');
+  const mismatches = await verifyWriteBack(app, table, id, data);
+  if (mismatches.length) throw errAPI(200, `Write-back verification failed for ${table}/${id}: ${mismatches.map(item => item.field).join(', ')}. The write may have succeeded partially; inspect before retrying.`);
+}
+
+function definitions(group, wrap) {
+  const suite = group === 'suites';
+  const baseTable = suite ? 'scan_check_suite' : 'scan_check';
+  const emit = (app, argv, record, summary) => report(app, argv, record, { summary, breadcrumbs: itemHints(group, record) });
+  return {
+    command: `${group} [subcommand]`,
+    describe: suite ? 'Manage scan suites and their check memberships' : 'Manage typed Instance Scan check definitions',
+    builder: y => {
+      y.command({ command: 'list', describe: `List ${group}`,
+        builder: p => {
+          p.option('query', { type: 'string', describe: 'Encoded query' })
+            .option('limit', { type: 'number', default: 50, describe: 'Maximum records (1–200)' })
+            .option('offset', { type: 'number', default: 0, describe: 'Pagination offset' });
+          return suite ? p : p.option('type', { choices: Object.keys(CHECK_TABLES), type: 'string', describe: 'Filter by check type' });
+        }, handler: wrap(async (argv, app) => {
+          const table = suite ? baseTable : (argv.type ? CHECK_TABLES[argv.type] : baseTable);
+          const records = await scanList(app.sdk, table, { limit: argv.limit, offset: argv.offset, query: argv.query,
+            fields: ['sys_id', 'name', 'active', ...(suite ? ['description'] : ['sys_class_name', 'short_description'])] });
+          report(app, argv, { table, records, count: records.length, limit: argv.limit, offset: argv.offset,
+            more_available: records.length === argv.limit ? null : false }, {
+            summary: `${records.length} scan ${group}`, breadcrumbs: [
+              ...records.slice(0, 5).map(record => hint('show', `jsn scan ${group} show ${unwrapSysId(record)}`, `Inspect ${getStringField(record, 'name')}`)),
+              hint('create', `jsn scan ${group} create${suite ? '' : ' --type table'} --data-file ${suite ? 'suite' : 'check'}.json`, 'Create an inactive definition'),
+              ...(records.length === argv.limit ? [hint('next', `jsn scan ${group} list --offset ${argv.offset + argv.limit} --limit ${argv.limit}${argv.type ? ` --type ${argv.type}` : ''}${argv.query ? ` --query ${quoteShellArg(argv.query)}` : ''}`, 'Next page')] : []),
+            ],
+          });
+        }) });
+      y.command({ command: 'show <identifier>', describe: `Inspect a ${suite ? 'suite and its members' : 'check'}`, builder: lookupOptions,
+        handler: wrap(async (argv, app) => {
+          const record = await resolveScanRecord(app.sdk, baseTable, argv.identifier);
+          if (suite) {
+            const members = await scanList(app.sdk, 'scan_check_suite_check', { limit: 200, query: `suite=${unwrapSysId(record)}^ORDERBYsys_id`, fields: ['sys_id', 'check'] });
+            record.members = members;
+            record.members_may_be_truncated = members.length === 200;
+          }
+          emit(app, argv, record, `Scan ${suite ? 'suite' : 'check'}: ${getStringField(record, 'name')}`);
+        }) });
+      y.command({ command: 'create', describe: `Create an inactive ${suite ? 'suite' : 'typed check'} unless active is explicitly supplied`,
+        builder: p => suite ? payloadOptions(p) : payloadOptions(p).option('type', { choices: Object.keys(CHECK_TABLES), type: 'string', demandOption: true, describe: 'Check type' }),
+        handler: wrap(async (argv, app) => {
+          const data = validateScanPayload(argv.type, buildRecordPayload(argv), { create: true, suite });
+          const table = suite ? baseTable : CHECK_TABLES[argv.type];
+          const record = await createRecord(app.sdk, { table, data });
+          await verify(app, table, unwrapSysId(record), data);
+          emit(app, argv, record, `Created scan ${suite ? 'suite' : 'check'}`);
+        }) });
+      for (const operation of ['update', 'activate', 'deactivate']) y.command({
+        command: `${operation} <identifier>`, describe: `${operation} a scan ${suite ? 'suite' : 'check'} without running it`,
+        builder: p => operation === 'update' ? payloadOptions(lookupOptions(p)) : lookupOptions(p),
+        handler: wrap(async (argv, app) => {
+          const record = await resolveScanRecord(app.sdk, baseTable, argv.identifier);
+          const kind = suite ? null : checkKind(record);
+          const patch = operation === 'update' ? validateScanPayload(kind, buildRecordPayload(argv), { suite, current: record }) : { active: operation === 'activate' };
+          if (!suite && operation === 'activate') validateScanPayload(kind, {
+            name: raw(record.name), script: raw(record.script), ...(kind === 'table' ? { table: raw(record.table), advanced: raw(record.advanced) } : {}),
+            ...(kind === 'column' ? { column_type: raw(record.column_type) } : {}),
+          }, { create: true });
+          await guardScope(app, record);
+          const table = suite ? baseTable : CHECK_TABLES[kind];
+          const updated = await updateRecord(app.sdk, { table, record, data: patch });
+          await verify(app, table, unwrapSysId(record), patch);
+          emit(app, argv, updated, `Updated scan ${suite ? 'suite' : 'check'}`);
+        }),
+      });
+      y.command({ command: 'delete <identifier>', describe: `Delete a ${suite ? 'suite' : 'check'} definition after confirmation`, builder: lookupOptions,
+        handler: wrap(async (argv, app) => {
+          const record = await resolveScanRecord(app.sdk, baseTable, argv.identifier);
+          await guardScope(app, record);
+          await confirmDelete(app, argv, `Delete scan ${suite ? 'suite' : 'check'} "${getStringField(record, 'name')}"?`);
+          const id = await deleteRecord(app.sdk, { table: suite ? baseTable : CHECK_TABLES[checkKind(record)], record });
+          report(app, argv, { sys_id: id, deleted: true }, { summary: 'Deleted scan definition', breadcrumbs: [hint('list', `jsn scan ${group} list`, 'Browse remaining definitions')] });
+        }) });
+      if (suite) for (const operation of ['add-check', 'remove-check']) y.command({
+        command: `${operation} <identifier>`, describe: `${operation === 'add-check' ? 'Add a check to' : 'Remove a check from'} a suite`,
+        builder: p => lookupOptions(p).option('check', { type: 'string', demandOption: true, describe: 'Check name or sys_id' }),
+        handler: wrap(async (argv, app) => {
+          const suiteRecord = await resolveScanRecord(app.sdk, baseTable, argv.identifier);
+          const check = await resolveScanRecord(app.sdk, 'scan_check', argv.check);
+          await guardScope(app, suiteRecord);
+          const data = { suite: unwrapSysId(suiteRecord), check: unwrapSysId(check) };
+          const table = 'scan_check_suite_check';
+          const members = await scanList(app.sdk, table, { query: `suite=${data.suite}^check=${data.check}`, limit: 2 });
+          if (members.length > 1) throw errUsage('Duplicate suite memberships exist; inspect and reconcile them before changing membership.');
+          let changed = false;
+          if (operation === 'add-check' && !members.length) {
+            const member = await createRecord(app.sdk, { table, data });
+            await verify(app, table, unwrapSysId(member), data);
+            changed = true;
+          } else if (operation === 'remove-check' && members.length) {
+            await confirmDelete(app, argv, 'Remove this check from the suite? The check definition will be retained.');
+            await deleteRecord(app.sdk, { table, record: members[0] });
+            changed = true;
+          }
+          report(app, argv, { ...data, changed, member: operation === 'add-check' }, { summary: 'Suite membership reconciled', breadcrumbs: itemHints(group, suiteRecord) });
+        }),
+      });
+      return y;
+    },
+    handler: wrap(async (argv, app) => report(app, argv, { commands: ['list', 'show', 'create', 'update', 'delete', 'activate', 'deactivate', ...(suite ? ['add-check', 'remove-check'] : [])] }, {
+      summary: `Scan ${group}`, breadcrumbs: [hint('list', `jsn scan ${group} list`, `Browse ${group}`)],
+    })),
+  };
+}
+
+export function scanCmd(wrap) {
+  return {
+    command: 'scan [subcommand]', describe: 'Instance Scan checks, suites, explicit targets, progress and findings',
+    builder: y => y.command(definitions('checks', wrap)).command(definitions('suites', wrap))
+      .command({ command: 'run', describe: 'Start an explicit target scan (confirmation required; no implicit full scan)',
+        builder: p => p.option('update-set', { type: 'string', describe: 'Update set name or sys_id; scans current records' })
+          .option('scope', { type: 'string', describe: 'Application scope value or sys_id' })
+          .option('record', { type: 'string', describe: 'Record sys_id; requires --table' })
+          .option('table', { type: 'string', describe: 'Table for --record' })
+          .option('full', { type: 'boolean', describe: 'Explicitly allow an instance-wide scan' })
+          .option('previous', { type: 'string', describe: 'Rerun a previous execution target; full scans also require --full' })
+          .option('suite', { type: 'string', describe: 'Optional active suite name or sys_id' })
+          .option('wait', { type: 'boolean', default: false, describe: 'Wait for completion; timeout does not cancel the scan' })
+          .option('timeout', { type: 'number', default: 120, describe: 'Maximum wait in seconds (1–3600)' }),
+        handler: wrap(async (argv, app) => {
+          if (!Number.isFinite(argv.timeout) || argv.timeout < 1 || argv.timeout > 3600) throw errUsage('--timeout must be from 1 to 3600 seconds.');
+          const plan = await prepareScan(app.sdk, argv);
+          await confirmDelete(app, argv, `Start scan of ${plan.target.kind} ${plan.target.name || plan.target.sys_id || plan.target.execution_id || 'the full instance'}${plan.suite_id ? ` using suite ${plan.suite_id}` : ''}?`);
+          const scheduled = await startScan(app.sdk, plan);
+          let data = { ...scheduled, status: 'scheduled', terminal: false };
+          if (argv.wait) {
+            try {
+              const deadline = Date.now() + argv.timeout * 1000;
+              while (Date.now() < deadline) {
+                try {
+                  data = { ...scheduled, ...await scanStatus(app.sdk, scheduled.execution_id, { allowInitializing: true }) };
+                } catch (error) {
+                  if (error.code !== 'not_found' && error.status !== 404) throw error;
+                  // The processor can return before its execution tracker is visible.
+                  data = { ...scheduled, status: 'scheduled', terminal: false };
+                }
+                if (data.terminal) { data = { ...scheduled, ...await scanResults(app.sdk, scheduled.execution_id) }; break; }
+                await new Promise(resolve => setTimeout(resolve, Math.min(2000, Math.max(0, deadline - Date.now()))));
+              }
+              if (!data.terminal) data.wait_timed_out = true;
+            } catch (error) {
+              throw errAPI(error.status || 0, `Scan ${scheduled.execution_id} was scheduled, but progress could not be read: ${error.message}. Use jsn scan status ${scheduled.execution_id}; do not resubmit automatically.`);
+            }
+          }
+          const breadcrumbs = executionHints(data);
+          if (data.terminal && !data.reusable_target) breadcrumbs.push(hint('rerun', 'jsn scan run --help', 'Choose a target for another scan'));
+          report(app, argv, data, { summary: `Scan ${data.execution_id}: ${data.status}${data.wait_timed_out ? ' (still running; wait timed out)' : ''}`, breadcrumbs });
+        }) })
+      .command({ command: 'status <id>', describe: 'Read scan execution progress',
+        handler: wrap(async (argv, app) => {
+          const data = await scanStatus(app.sdk, argv.id);
+          report(app, argv, data, { summary: `Scan ${data.status}: ${data.message}`, breadcrumbs: executionHints(data) });
+        }) })
+      .command({ command: 'results <id>', describe: 'Read findings and check execution coverage; unreadable data is not zero',
+        builder: p => p.option('limit', { type: 'number', default: 50, describe: 'Maximum findings/check rows (1–200); truncation is reported' }),
+        handler: wrap(async (argv, app) => {
+          const data = await scanResults(app.sdk, argv.id, boundedLimit(argv.limit));
+          report(app, argv, data, { summary: `Scan ${data.status}; ${data.findings_count ?? 'unknown'} findings; ${data.checks_executed ?? 'unknown'} recorded check executions${data.incomplete ? '; incomplete data' : ''}`, breadcrumbs: executionHints(data) });
+        }) })
+      .command({ command: 'cancel <id>', describe: 'Request cancellation of this scan after confirmation',
+        handler: wrap(async (argv, app) => {
+          const status = await scanStatus(app.sdk, argv.id);
+          if (!status.terminal) await confirmDelete(app, argv, `Cancel scan ${argv.id}?`);
+          const data = status.terminal ? { ...status, cancellation_requested: false } : await cancelScan(app.sdk, argv.id);
+          report(app, argv, data, { summary: data.cancellation_requested ? `Cancellation requested: ${argv.id}` : 'Scan already finished; no cancellation sent', breadcrumbs: executionHints(data) });
+        }) }),
+    handler: wrap(async (argv, app) => report(app, argv, { commands: ['checks', 'suites', 'run', 'status', 'results', 'cancel'] }, { summary: 'Instance Scan', breadcrumbs: rootHints() })),
+  };
+}