@jacebenson/jsn 4.3.13-dev.100.1 → 4.3.13-dev.102.1

package/README.md

@@ -32,6 +32,57 @@ under npm's `dev` tag. Versions include the workflow run number and attempt
 The npm trusted publisher for `publish-dev.yml` must authorize the repository's
 `dev` GitHub environment, alongside the production publishing configuration.
 
+### Knowledge search
+
+Use `jsn knowledge search "VPN setup" --profile work` (alias `kb`) to search
+accessible articles, then `jsn knowledge show KB0000010 --profile work` to read
+one. Search supports bounded `--limit`/`--offset`, knowledge-base sys_ids with
+`--kb`, and `--language`. JSON preserves native HTML; human output uses Markdown.
+Hints preserve an explicitly selected profile/instance. The Knowledge API plugin
+(`sn_km_api`) must be available; access is evaluated by that API, with no fallback
+to direct table reads. Reads do not request view-count updates. See the
+[Knowledge API reference](https://www.servicenow.com/docs/r/yokohama/api-reference/rest-apis/knowledge-api.html).
+
+### Instance Scan
+
+`jsn scan` manages checks and suites and runs scans against an explicit target.
+Use `jsn scan --help` and each subcommand's `--help` to discover the options.
+
+```bash
+jsn scan checks list --profile dev
+jsn scan checks create --type table --data-file check.json --profile dev
+jsn scan checks activate <check-id> --profile dev
+jsn scan suites add-check <suite-id> --check <check-id> --profile dev
+jsn scan run --update-set "My change" --suite "My suite" --wait --profile dev
+jsn scan run --table sys_script_include --record <record-id> --profile dev
+jsn scan results <execution-id> --profile dev
+```
+
+Check types are `table`, `column`, `linter`, and `script`. Definitions are created
+inactive unless the payload explicitly sets `active: true`; activation never
+starts a scan. Both checks and suites support list/show/create/update/delete and
+activate/deactivate. Suites also support add-check/remove-check.
+
+Runs require an update set, scope, record plus table, or explicit `--full`.
+Instance-wide scans may traverse many tables even when a check's script only
+examines a few records. Starting and cancelling a scan require confirmation;
+use `--force` only after approving that operation. `--wait --timeout 120` bounds
+the wait, not the scan's lifetime. A timed-out wait keeps the execution id and
+does not cancel or resubmit the scan. Use `status`, `results`, or `cancel` next.
+
+Update-set scans examine current instance records, not the historical XML
+versions. Inactive records may be skipped. Script-only checks do not participate
+in record/update-set scans; use an explicitly instance-wide suite run to execute
+them. Execution success does not mean zero findings or complete test coverage:
+results report recorded check executions, finding counts, unreadable sources,
+and truncated lists separately. A result's rerun hint preserves the previous
+target combination and requires `--full` again for instance-wide scans.
+
+Every command returns next-step breadcrumbs in human and JSON output, retaining
+an explicitly selected profile or instance. `updatesets show` also offers a scan
+hint. Recommendation/generation of new checks is not part of this command;
+JSN contains no AI and does not infer missing business requirements.
+
 ### Supported versions
 
 Only the current release and the two preceding releases in each channel are
@@ -92,3 +143,26 @@ This applies to root help, root JSON, `discover`, and root shell completion.
 Use `jsn --all-commands --help` or `jsn discover --all-commands --json` to inspect
 every registered command. Explicit command paths remain available and ServiceNow
 ACLs decide access. Reauthenticate (or refresh OAuth) after roles change.
+
+### Ordering catalog items
+
+Use `jsn catalogitems search "laptop" --profile work`, then
+`jsn catalogitems describe <item-sys-id> --profile work` to inspect pricing and
+variable definitions through the native Service Catalog API. Create a JSON file
+mapping variable names to values, then preview with
+`jsn catalogitems order <item-sys-id> --variables-file variables.json --dry-run --profile work`.
+Omit `--dry-run` to submit after confirmation. `--quantity` defaults to one;
+`--requested-for` accepts a user sys_id subject to instance delegation rules.
+
+Orders use `order_now`, preserving catalog fulfillment rather than inserting an
+RITM directly. The command handles standard catalog items; record producers and
+order guides require separate workflows. Server rules validate mandatory and
+dynamic variables at submission; a preview does not validate those rules. Preview
+output lists variable names, not entered values. This operation requires a
+write-enabled profile (also for previews), but no development update set.
+Confirmation follows the existing profile policy; automation can supply `--force`
+only for an approved order. Timeout or incomplete response is an uncertain
+outcome: inspect requests before retrying. JSN does not automatically submit a
+second order. `create/list/show` retain their definition-management behavior.
+
+See the [Service Catalog API reference](https://www.servicenow.com/docs/r/api-reference/rest-apis/c_ServiceCatalogAPI.html).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "4.3.13-dev.100.1",
+  "version": "4.3.13-dev.102.1",
   "description": "A command-line interface for ServiceNow that follows the Unix philosophy: simple, composable, and scriptable.",
   "type": "module",
   "bin": {

package/skills/servicenow/SKILL.md

@@ -24,7 +24,7 @@ For development:
 1. Choose or create the application scope and update set.
 2. Do the work, keeping related changes together.
 3. Verify the results on the instance and report where changes were captured.
-4. Offer to create ATFs and instance scans to verify the outcomes.
+4. Offer to run relevant existing ATFs and instance scans, or create missing checks.
 5. Ask whether anything else belongs in the update set. If the user confirms
    it is finished, complete it with notes.
 

package/src/cli.js

@@ -22,6 +22,7 @@ import { authCmd } from './commands/auth.js';
 import { recordsCmd } from './commands/records.js';
 import { attachmentsCmd } from './commands/attachments.js';
 import { cmdbCmd } from './commands/cmdb.js';
+import { knowledgeCmd } from './commands/knowledge.js';
 import { snippetsCmd } from './commands/snippets.js';
 import { catalogCmd } from './commands/catalog.js';
 import { incidentsCmd } from './commands/incidents.js';
@@ -72,6 +73,7 @@ import { logsCmd } from './commands/logs.js';
 import { scrapiCmd } from './commands/scrapi.js';
 import { b4rulesCmd } from './commands/b4rules.js';
 import { atfCmd } from './commands/atf.js';
+import { scanCmd } from './commands/scan.js';
 import { approvalsCmd } from './commands/approvals.js';
 import { historyCmd } from './commands/history.js';
 import { perfCmd } from './commands/perf.js';
@@ -411,6 +413,7 @@ export function buildCLI() {
     .command(propertiesCmd(wrap))
     // DATA
     .command(cmdbCmd(wrap))
+    .command(knowledgeCmd(wrap))
     .command(recordsCmd(wrap))
     .command(attachmentsCmd(wrap))
     .command(transactionsCmd(wrap))
@@ -421,6 +424,7 @@ export function buildCLI() {
     .command(codesearchCmd(wrap))
     // DEVELOPER
     .command(atfCmd(wrap))
+    .command(scanCmd(wrap))
     .command(approvalsCmd(wrap))
     .command(skippedUpdatesCmd(wrap))
     .command(perfCmd(wrap))

package/src/command-audience.js

@@ -2,8 +2,10 @@
 // Explicit command paths and --all-commands remain available to every account.
 const BASIC_COMMANDS = new Set([
   'incidents', 'changes', 'requests', 'tasks', 'tickets', 'approvals', 'records',
+  'knowledge',
   'groups', 'groupmembers', 'grouproles', 'users', 'setup', 'auth', 'skill',
   'version', 'docs', 'history', 'discover', 'completion',
+  'catalogitems',
 ]);
 
 export async function detectCommandAudience(sdk, username, instanceURL = sdk?.baseURL) {

package/src/commands/catalog-order.js

@@ -0,0 +1,93 @@
+import { parseDataArg, confirmDelete, quoteShellArg } from '../helpers.js';
+import { errAPI, errUsage } from '../errors.js';
+
+const ID = /^[a-f0-9]{32}$/i;
+const API = '/api/sn_sc/servicecatalog/items';
+const object = v => v && typeof v === 'object' && !Array.isArray(v);
+
+function emit(app, argv, data, summary, breadcrumbs = []) {
+  const connection = argv.profile ? ` --profile ${quoteShellArg(argv.profile)}` : argv.instance ? ` --instance ${quoteShellArg(argv.instance)}` : '';
+  app.ok(data, { summary, breadcrumbs: breadcrumbs.map(h => ({ ...h, cmd: h.cmd + connection })) });
+}
+function requireId(id) { if (!ID.test(id || '')) throw errUsage('Use the full catalog item sys_id; find it with catalogitems search.'); }
+async function describe(app, id) {
+  requireId(id);
+  const response = await app.sdk.request(`${app.sdk.baseURL}${API}/${id}`, { method: 'GET' });
+  if (!object(response?.result) || response.result.sys_id !== id) throw errAPI(200, 'Catalog API returned no readable item with the requested identity.');
+  return response.result;
+}
+function itemHints(id) {
+  return [{ action: 'describe', cmd: `jsn catalogitems describe ${id}`, description: 'Inspect catalog inputs and pricing' },
+    { action: 'preview', cmd: `jsn catalogitems order ${id} --dry-run --variables-file variables.json`, description: 'Preview an order without submitting' }];
+}
+
+export function catalogOrderCommands(wrap) {
+  return [
+    { command: 'search <text>', describe: 'Find requestable items through the Service Catalog API',
+      builder: y => y.positional('text', { type: 'string' }).option('limit', { type: 'number', default: 20, describe: 'Maximum items (1–100)' }),
+      handler: wrap(async (argv, app) => {
+        if (typeof argv.text !== 'string' || !argv.text.trim()) throw errUsage('Provide nonempty catalog search text.');
+        if (!Number.isInteger(argv.limit) || argv.limit < 1 || argv.limit > 100) throw errUsage('--limit must be from 1 to 100.');
+        const params = new URLSearchParams({ sysparm_text: argv.text.trim(), sysparm_limit: String(argv.limit) });
+        const response = await app.sdk.request(`${app.sdk.baseURL}${API}?${params}`, { method: 'GET' });
+        if (!Array.isArray(response?.result) || response.result.some(i => !object(i) || !ID.test(i.sys_id || ''))) throw errAPI(200, 'Catalog API returned no valid item list.');
+        emit(app, argv, { items: response.result, count: response.result.length, limit: argv.limit,
+          possibly_truncated: response.result.length === argv.limit }, `${response.result.length} catalog item(s)`,
+        response.result.flatMap(i => itemHints(i.sys_id).slice(0, 1)));
+      }) },
+    { command: 'describe <id>', aliases: ['inputs'], describe: 'Read requestable item details, pricing and variable definitions',
+      builder: y => y.positional('id', { type: 'string' }),
+      handler: wrap(async (argv, app) => {
+        const item = await describe(app, argv.id);
+        emit(app, argv, item, item.name || item.short_description || argv.id, itemHints(argv.id));
+      }) },
+    { command: 'order <id>', describe: 'Submit a catalog order with explicit confirmation',
+      builder: y => y.positional('id', { type: 'string' })
+        .option('variables', { type: 'string', describe: 'JSON object of catalog variable names/values' })
+        .option('variables-file', { type: 'string', describe: 'Read the variables object from a JSON file' })
+        .option('quantity', { type: 'number', default: 1, describe: 'Positive integer quantity (max 1000)' })
+        .option('requested-for', { type: 'string', describe: 'User sys_id; instance delegation rules still apply' })
+        .option('dry-run', { type: 'boolean', default: false, describe: 'Read item details and preview variable names; no order is submitted' })
+        .epilogue('Use describe to inspect variables first. Server-side rules validate the order; a preview does not prove submission will succeed. Existing create/list/show commands manage definitions. Orders require a write-enabled profile, including dry runs. No application/update-set selection is needed.'),
+      handler: wrap(async (argv, app) => {
+        requireId(argv.id);
+        if (!Number.isInteger(argv.quantity) || argv.quantity < 1 || argv.quantity > 1000) throw errUsage('--quantity must be an integer from 1 to 1000.');
+        const requestedFor = argv.requestedFor ?? argv['requested-for'];
+        if (requestedFor !== undefined && !ID.test(requestedFor)) throw errUsage('--requested-for requires a user sys_id.');
+        const file = argv.variablesFile ?? argv['variables-file'];
+        if (argv.variables !== undefined && file !== undefined) throw errUsage('Choose --variables or --variables-file, not both.');
+        const variables = argv.variables !== undefined || file !== undefined
+          ? parseDataArg({ data: argv.variables, 'data-file': file }) : {};
+        if (!object(variables)) throw errUsage('Catalog variables must be a JSON object.');
+        const item = await describe(app, argv.id);
+        if (item.sys_class_name && item.sys_class_name !== 'sc_cat_item') throw errUsage('order supports standard catalog items; record producers and order guides need their own submission workflows.');
+        if (item.active === false || item.active === 'false' || item.can_order === false) throw errUsage('This item is not currently orderable.');
+        const plan = { item_id: argv.id, name: item.name || item.short_description, quantity: argv.quantity,
+          requested_for: requestedFor || null, variable_names: Object.keys(variables) };
+        if (argv.dryRun ?? argv['dry-run']) return emit(app, argv, { ...plan, submitted: false, server_validation: 'not performed' }, 'Catalog order preview; nothing submitted', itemHints(argv.id));
+        const rerun = ['catalogitems', 'order', argv.id, '--quantity', String(argv.quantity),
+          ...(requestedFor ? ['--requested-for', requestedFor] : []),
+          ...(file ? ['--variables-file', file] : Object.keys(variables).length ? ['--variables-file', '<variables.json>'] : [])];
+        try {
+          await confirmDelete(app, argv, `Order ${argv.quantity} × ${plan.name || argv.id}${requestedFor ? ` for ${requestedFor}` : ''}?`, { rerun });
+        } catch (error) {
+          if (error.message === 'Deletion cancelled') throw errUsage('Catalog order cancelled.');
+          throw error;
+        }
+        const body = { sysparm_quantity: argv.quantity, variables, ...(requestedFor ? { sysparm_requested_for: requestedFor } : {}) };
+        let response;
+        try {
+          response = await app.sdk.request(`${app.sdk.baseURL}${API}/${argv.id}/order_now`, { method: 'POST', body: JSON.stringify(body) });
+        } catch (error) {
+          if (error.status >= 400 && error.status < 500 && error.status !== 408) throw errAPI(error.status, 'Catalog order was rejected. Check item access, required variables and requested-for eligibility.');
+          throw errAPI(error.status || 0, 'Catalog submission did not return a confirmed order. Inspect your requests before retrying; the order may have been placed.');
+        }
+        const result = response?.result;
+        const requestId = result?.request_id || result?.sys_id, number = result?.request_number || result?.number;
+        if (!object(result) || result.error || !ID.test(requestId || '') || typeof number !== 'string' || !number.trim()) throw errAPI(200, 'Catalog response did not confirm an order identity. Inspect your requests before retrying; do not resubmit automatically.');
+        emit(app, argv, { item_id: argv.id, quantity: argv.quantity, request_id: requestId, request_number: number, submitted: true },
+          `Ordered: ${number}`, [{ action: 'request', cmd: `jsn records get --table sc_request --sys-id ${requestId}`, description: 'Read the request header' },
+            { action: 'items', cmd: `jsn requests list --query ${quoteShellArg(`request=${requestId}`)}`, description: 'Track the requested items' }]);
+      }) },
+  ];
+}

package/src/commands/catalog.js

@@ -1,9 +1,10 @@
-import { getStringField, interactiveList, resolveItemOptionType } from '../helpers.js';
+import { getStringField, interactiveList, resolveItemOptionType, formatCommandList, quoteShellArg } from '../helpers.js';
+import { catalogOrderCommands } from './catalog-order.js';
 import { resolveSysId } from '../resolve-record.js';
 import { declareCapabilities } from '../capabilities.js';
 import { enrichCatalogItem, buildCatalogFormatted } from './catalog/enrich.js';
 
-declareCapabilities('catalogitems', { mutationSubcommands: ['create'] });
+declareCapabilities('catalogitems', { mutationSubcommands: ['create', 'order'], mutationContextExemptSubcommands: ['order'], localPreviewSubcommands: ['order'] });
 
 export function catalogCmd(wrap) {
   return {
@@ -11,6 +12,7 @@ export function catalogCmd(wrap) {
     aliases: ['ci'],
     describe: 'Manage Service Catalog items',
     builder: (yargs) => {
+      for (const command of catalogOrderCommands(wrap)) yargs.command(command);
       return yargs
         .command({
           command: 'create',
@@ -148,14 +150,10 @@ export function catalogCmd(wrap) {
           }),
         });
     },
-    handler: () => {
-      console.log('Service Catalog management.');
-      console.log('');
-      console.log('Commands:');
-      console.log('  create     Create a catalog item');
-      console.log('  list       Browse catalog items');
-      console.log('  show <id>  Show catalog item');
-    },
+    handler: wrap(async (argv, app) => app.ok({ subcommands: argv.subcommands || [],
+      _formatted: formatCommandList({ title: 'Service Catalog', commands: argv.subcommands || [] }) },
+    { summary: 'Service Catalog: search, describe and order items; manage definitions with create/list/show',
+      breadcrumbs: [{ action: 'search', cmd: 'jsn catalogitems search <text>' + (argv.profile ? ` --profile ${quoteShellArg(argv.profile)}` : argv.instance ? ` --instance ${quoteShellArg(argv.instance)}` : ''), description: 'Find requestable items' }] })),
   };
 }
 

package/src/commands/knowledge.js

@@ -0,0 +1,75 @@
+import TurndownService from 'turndown';
+import { formatCommandList, quoteShellArg } from '../helpers.js';
+import { errAPI, errUsage } from '../errors.js';
+
+const API = '/api/sn_km_api/knowledge/articles';
+const markdown = new TurndownService();
+const sysId = /^[a-f0-9]{32}$/i;
+const articleId = value => typeof value === 'string' && (sysId.test(value) || /^KB\d+$/i.test(value));
+
+function emit(app, argv, data, summary, breadcrumbs = []) {
+  const connection = argv.profile ? ` --profile ${quoteShellArg(argv.profile)}`
+    : argv.instance ? ` --instance ${quoteShellArg(argv.instance)}` : '';
+  app.ok(data, { summary, breadcrumbs: breadcrumbs.map(h => ({ ...h, cmd: h.cmd + connection })) });
+}
+
+async function read(sdk, path, params) {
+  const response = await sdk.request(`${sdk.baseURL}${API}${path}?${params}`, { method: 'GET' });
+  const result = response?.result;
+  if (!result || typeof result !== 'object' || Array.isArray(result)) throw errAPI(200, 'Malformed Knowledge API response.');
+  const code = result.meta?.status?.code;
+  if (code !== undefined && Number(code) !== 200) throw errAPI(Number(code) || 500, 'Knowledge API rejected the request.');
+  return result;
+}
+
+export function knowledgeCmd(wrap) {
+  return {
+    command: 'knowledge [subcommand]', aliases: ['kb'],
+    describe: 'Search and read knowledge articles through the Knowledge API',
+    handler: wrap(async (argv, app) => emit(app, argv,
+      { subcommands: argv.subcommands || [], _formatted: formatCommandList({ title: 'Knowledge articles', commands: argv.subcommands || [] }) },
+      'Search and read knowledge articles', [{ action: 'search', cmd: 'jsn knowledge search <text>', description: 'Find accessible articles' }])),
+    builder: y => y
+      .epilogue('Requires the Knowledge API (sn_km_api). Uses its access checks; no fallback to direct knowledge-table reads. Reading does not request view-count updates.')
+      .command({ command: 'search <text>', describe: 'Search accessible knowledge articles',
+        builder: p => p.positional('text', { type: 'string', describe: 'Search text; quote multiple words' })
+          .option('limit', { type: 'number', default: 20, describe: 'Maximum articles (1–100)' })
+          .option('offset', { type: 'number', default: 0, describe: 'Starting result offset' })
+          .option('kb', { type: 'string', describe: 'Comma-separated knowledge-base sys_ids' })
+          .option('language', { type: 'string', describe: 'Two-letter language codes, comma-separated, or all' }),
+        handler: wrap(async (argv, app) => {
+          if (typeof argv.text !== 'string' || !argv.text.trim()) throw errUsage('Provide nonempty search text.');
+          if (!Number.isInteger(argv.limit) || argv.limit < 1 || argv.limit > 100) throw errUsage('--limit must be from 1 to 100.');
+          if (!Number.isInteger(argv.offset) || argv.offset < 0) throw errUsage('--offset must be a nonnegative integer.');
+          if (argv.kb !== undefined && !String(argv.kb).split(',').every(id => sysId.test(id))) throw errUsage('--kb requires knowledge-base sys_ids.');
+          if (argv.language !== undefined && !/^(all|[a-z]{2}(,[a-z]{2})*)$/i.test(argv.language)) throw errUsage('Use two-letter --language codes or all.');
+          const params = new URLSearchParams({ query: argv.text.trim(), limit: String(argv.limit), offset: String(argv.offset) });
+          if (argv.kb) params.set('kb', argv.kb);
+          if (argv.language) params.set('language', argv.language);
+          const result = await read(app.sdk, '', params);
+          if (!Array.isArray(result.articles) || result.articles.some(a => !a || typeof a !== 'object' || Array.isArray(a))) throw errAPI(200, 'Knowledge API returned no valid article list.');
+          const breadcrumbs = result.articles.flatMap(a => {
+            const id = articleId(a.number) ? a.number : String(a.id || '').replace(/^kb_knowledge:/, '');
+            return articleId(id) ? [{ action: 'show', cmd: `jsn knowledge show ${id}`, description: a.title || id }] : [];
+          });
+          const base = `jsn knowledge search ${quoteShellArg(argv.text.trim())} --limit ${argv.limit}`
+            + (argv.kb ? ` --kb ${quoteShellArg(argv.kb)}` : '') + (argv.language ? ` --language ${quoteShellArg(argv.language)}` : '');
+          const total = result.meta?.count;
+          const hasMore = typeof total === 'number' ? argv.offset + result.articles.length < total : result.articles.length === argv.limit;
+          if (hasMore) breadcrumbs.push({ action: 'next', cmd: `${base} --offset ${argv.offset + argv.limit}`, description: 'Next result page' });
+          emit(app, argv, { ...result, count: result.articles.length,
+            _formatted: result.articles.map(a => `${a.number || a.id || ''}  ${a.title || ''}\n${a.snippet || ''}`).join('\n\n') || 'No accessible articles matched.' },
+          `${result.articles.length} knowledge article(s)`, breadcrumbs);
+        }) })
+      .command({ command: 'show <id>', describe: 'Read an article by KB number or sys_id',
+        builder: p => p.positional('id', { type: 'string' }),
+        handler: wrap(async (argv, app) => {
+          if (!articleId(argv.id)) throw errUsage('Use a KB number or full article sys_id.');
+          const article = await read(app.sdk, `/${encodeURIComponent(argv.id)}`, new URLSearchParams());
+          if (!sysId.test(article.sys_id || '') || typeof article.content !== 'string') throw errAPI(200, 'Knowledge API returned no readable article content.');
+          emit(app, argv, { ...article, _formatted: `${article.number || argv.id}: ${article.short_description || ''}\n\n${markdown.turndown(article.content)}` },
+            article.short_description || article.number || argv.id,
+            [{ action: 'search', cmd: 'jsn knowledge search <text>', description: 'Find more articles' }]);
+        }) }),
+  };
+}

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() })),
+  };
+}

package/src/commands/updatesets.js

@@ -365,6 +365,7 @@ export async function formatUpdateSetDetail(app, record) {
   const stateRaw = String(full.state?.value ?? full.state ?? '').toLowerCase();
   const isClosed = ['complete', 'committed'].includes(stateRaw);
   const hints = [];
+  hints.push({ action: 'scan', cmd: `jsn scan run --update-set ${sysID}${app.session?.profileName ? ` --profile ${quoteShellArg(app.session.profileName)}` : ''}`, description: 'Offer an explicit scan of current records before completing or promoting this set' });
   if (isClosed) {
     hints.push({
       action: 'set',

package/src/help.js

@@ -28,6 +28,7 @@ function renderGroup(name, commands) {
 }
 
 const CORE_COMMANDS = [
+  { name: 'knowledge', alias: 'kb', desc: 'Search and read knowledge articles' },
   { name: 'incidents', alias: 'inc', desc: 'Manage incidents' },
   { name: 'changes', alias: 'chg', desc: 'Manage change requests' },
   { name: 'requests', alias: 'req', desc: 'Manage service catalog requests' },
@@ -132,6 +133,7 @@ const CONFIG_COMMANDS = [
 ];
 
 const DEVELOPER_COMMANDS = [
+  { name: 'scan', desc: 'Instance Scan checks, suites, explicit targets, progress and findings' },
   { name: 'atf', desc: 'Automated Test Framework (list, suites, run, results)' },
   { name: 'eval', desc: 'Run server-side JavaScript' },
   { name: 'rest', desc: 'Raw REST API calls' },

package/src/scan.js

@@ -0,0 +1,249 @@
+import { SaxesParser } from 'saxes';
+import { getRecord, recordListParams } from './records-engine.js';
+import { isSysId, unwrapSysId } from './resolve-record.js';
+import { errAPI, errNotFound, errUsage } from './errors.js';
+
+export const CHECK_TABLES = {
+  table: 'scan_table_check', column: 'scan_column_type_check',
+  linter: 'scan_linter_check', script: 'scan_script_only_check',
+};
+export const raw = value => value && typeof value === 'object' ? (value.value ?? '') : value;
+export const active = record => [true, 'true', '1', 1].includes(raw(record?.active));
+export const referenceId = value => {
+  const id = raw(value) || value?.link?.split('/').at(-1);
+  return isSysId(id) ? id : '';
+};
+
+export function requireId(value, label = 'execution') {
+  if (!isSysId(value)) throw errUsage(`Use a full 32-character sys_id for ${label}.`);
+  return value;
+}
+
+export function boundedLimit(value = 50) {
+  if (!Number.isInteger(value) || value < 1 || value > 200) throw errUsage('--limit must be an integer from 1 to 200.');
+  return value;
+}
+
+export async function scanList(sdk, table, { limit = 50, offset = 0, fields, query } = {}) {
+  boundedLimit(limit);
+  if (!Number.isInteger(offset) || offset < 0) throw errUsage('--offset must be a nonnegative integer.');
+  const params = recordListParams({ limit, offset, fields, query, displayValue: 'false' });
+  return sdk.listStrict(table, params);
+}
+
+export async function resolveScanRecord(sdk, table, identifier, matchField = 'name') {
+  const record = await getRecord(sdk, { table, identifier, matchField, displayValues: 'raw', resource: table });
+  if (table !== 'scan_check') return record;
+  const subtype = String(raw(record.sys_class_name) || '');
+  if (!Object.values(CHECK_TABLES).includes(subtype)) return record;
+  const concrete = await sdk.get(subtype, unwrapSysId(record));
+  if (!concrete || unwrapSysId(concrete) !== unwrapSysId(record)) throw errUsage('The concrete check definition is unavailable; inspect its class and permissions before changing it.');
+  return { ...record, ...concrete };
+}
+
+const COMMON_FIELDS = ['name', 'description', 'short_description', 'active', 'category', 'priority',
+  'script', 'run_condition', 'finding_type', 'resolution_details', 'documentation_url', 'score_min', 'score_max', 'score_scale'];
+
+export function validateScanPayload(kind, input, { create = false, suite = false, current = {} } = {}) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw errUsage('The payload must be a JSON object.');
+  if (!suite && !CHECK_TABLES[kind]) throw errUsage('Choose --type table, column, linter, or script.');
+  const fields = suite ? ['name', 'description', 'active', 'private'] : [...COMMON_FIELDS,
+    ...(kind === 'table' ? ['table', 'conditions', 'advanced', 'use_manifest'] : []),
+    ...(kind === 'column' ? ['column_type'] : [])];
+  for (const field of Object.keys(input)) {
+    if (!fields.includes(field)) throw errUsage(`Unsupported ${suite ? 'suite' : kind + ' check'} field: ${field}`);
+  }
+  const data = { ...input };
+  for (const field of ['active', 'private', 'advanced', 'use_manifest']) {
+    if (data[field] === undefined) continue;
+    if (![true, false, 'true', 'false'].includes(data[field])) throw errUsage(`${field} must be true or false.`);
+    data[field] = data[field] === true || data[field] === 'true';
+  }
+  if ((create || data.name !== undefined) && (typeof data.name !== 'string' || !data.name.trim())) throw errUsage('A nonempty name is required.');
+  if (data.script !== undefined && typeof data.script !== 'string') throw errUsage('script must be a string.');
+  if (create && data.active === undefined) data.active = false;
+  if (data.table !== undefined && !/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(data.table)) throw errUsage('Invalid target table name.');
+  if (data.column_type !== undefined && !['script', 'xml', 'html'].includes(data.column_type)) throw errUsage('column_type must be script, xml, or html.');
+  if (!suite) {
+    const script = data.script ?? raw(current.script);
+    const advanced = data.advanced ?? active({ active: current.advanced });
+    if (create && kind === 'table' && !data.table) throw errUsage('Table checks require a table.');
+    if (create && kind === 'column' && !data.column_type) throw errUsage('Column checks require column_type.');
+    if ((create || Object.hasOwn(data, 'script') || Object.hasOwn(data, 'advanced'))
+      && (kind !== 'table' || advanced) && (typeof script !== 'string' || !script.trim())) {
+      throw errUsage('This check type requires a nonempty script.');
+    }
+  }
+  return data;
+}
+
+export function checkKind(record) {
+  const table = String(raw(record.sys_class_name) || '');
+  const kind = Object.keys(CHECK_TABLES).find(key => CHECK_TABLES[key] === table);
+  if (!kind) throw errUsage('Unknown or unreadable check class; inspect the check before changing it.');
+  return kind;
+}
+
+function decodeAjax(xml) {
+  let answer;
+  const parser = new SaxesParser();
+  parser.on('doctype', () => { throw errAPI(200, 'Unexpected document type in scan response.'); });
+  parser.on('opentag', node => { if (node.name === 'xml') answer = node.attributes.answer; });
+  try { parser.write(xml).close(); } catch { throw errAPI(200, 'Malformed scan processor XML response.'); }
+  if (typeof answer !== 'string') throw errAPI(200, 'Scan processor returned no answer; check endpoint access.');
+  return answer;
+}
+
+export async function scanAjax(sdk, method, parameters) {
+  const query = new URLSearchParams({ sysparm_processor: 'ScanAjaxProcessor', sysparm_name: method, ...parameters });
+  return decodeAjax(await sdk.rawRequest(`${sdk.baseURL}/xmlhttp.do?${query}`, { method: 'POST' }));
+}
+
+const TERMINAL = new Set(['successful', 'failed', 'cancelled']);
+const STATES = { '0': 'pending', '1': 'running', '2': 'successful', '3': 'failed', '4': 'cancelled',
+  pending: 'pending', running: 'running', successful: 'successful', failed: 'failed',
+  cancelled: 'cancelled', canceled: 'cancelled' };
+
+export async function scanStatus(sdk, id, { allowInitializing = false } = {}) {
+  requireId(id);
+  const tracker = await sdk.get('sys_execution_tracker', id);
+  if (!tracker) throw errNotFound('scan execution', id);
+  if (!raw(tracker.type) && allowInitializing) return { execution_id: id, status: 'pending', terminal: false,
+    percent_complete: null, message: 'Execution tracker is initializing', result_id: null };
+  if (raw(tracker.type) === 'sys.instance_scan.queue') return { execution_id: id, status: 'pending', terminal: false,
+    percent_complete: raw(tracker.percent_complete) ?? null, message: raw(tracker.message) || 'Scan is queued', result_id: null };
+  if (raw(tracker.type) !== 'instance_scan') throw errUsage('This execution tracker is not an Instance Scan.');
+  const state = STATES[String(raw(tracker.state)).toLowerCase()] || 'unknown';
+  let resultId = '';
+  if (raw(tracker.result)) {
+    try { resultId = referenceId(JSON.parse(raw(tracker.result)).result_id); } catch { /* reported as unavailable below */ }
+  }
+  return { execution_id: id, status: state, terminal: TERMINAL.has(state),
+    percent_complete: raw(tracker.percent_complete) ?? null,
+    message: raw(tracker.message) || '', result_id: resultId || null };
+}
+
+async function resolveSuite(sdk, identifier) {
+  const suite = await resolveScanRecord(sdk, 'scan_check_suite', identifier);
+  if (!active(suite)) throw errUsage('The selected suite is inactive or its active state is unreadable. Activate it explicitly first.');
+  return unwrapSysId(suite);
+}
+
+export async function prepareScan(sdk, argv) {
+  const previous = argv.previous;
+  const updateSet = argv.updateSet ?? argv['update-set'];
+  for (const value of [previous, updateSet, argv.scope, argv.record, argv.suite]) {
+    if (value !== undefined && (typeof value !== 'string' || !value.trim())) throw errUsage('Scan target and suite identifiers must be nonempty strings.');
+  }
+  const selectors = [updateSet, argv.scope, argv.record, previous].filter(value => value !== undefined).length;
+  if (selectors + Number(Boolean(argv.full)) !== 1 && !(previous && argv.full && selectors === 1)) {
+    throw errUsage('Choose exactly one target: --update-set, --scope, --record with --table, --full, or --previous.');
+  }
+  if (Boolean(argv.table) !== Boolean(argv.record)) throw errUsage('--record and --table must be supplied together.');
+  if (previous && argv.suite) throw errUsage('--previous preserves its source suite; do not combine it with --suite.');
+  let target;
+  if (previous) {
+    const status = await scanStatus(sdk, previous);
+    if (!status.terminal || !status.result_id) throw errUsage('The previous scan must have finished and have a readable result.');
+    const result = await sdk.get('scan_result', status.result_id);
+    const comboId = referenceId(result?.combo);
+    if (!comboId) throw errUsage('The previous scan has no reusable target combination. Choose an explicit target.');
+    const combo = await sdk.get('scan_combo', comboId);
+    if (!combo) throw errUsage('The previous scan combination is unavailable.');
+    if (!raw(combo.targets) && !argv.full) throw errUsage('The previous scan was instance-wide. Repeat with --full to approve that breadth.');
+    target = { kind: 'previous', execution_id: previous, combo_id: comboId, full: !raw(combo.targets) };
+  } else if (updateSet !== undefined) {
+    const record = await resolveScanRecord(sdk, 'sys_update_set', updateSet);
+    target = { kind: 'update_set', sys_id: unwrapSysId(record), name: raw(record.name),
+      note: 'Scans current instance records referenced by this update set, not historical XML versions. Script-only checks do not participate.' };
+  } else if (argv.scope !== undefined) {
+    const record = await resolveScanRecord(sdk, 'sys_scope', argv.scope, 'scope');
+    target = { kind: 'scope', sys_id: unwrapSysId(record), name: raw(record.scope) };
+  } else if (argv.record !== undefined) {
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(argv.table)) throw errUsage('Invalid target table.');
+    const record = await resolveScanRecord(sdk, argv.table, argv.record, 'sys_id');
+    target = { kind: 'record', table: argv.table, sys_id: unwrapSysId(record),
+      inactive: raw(record.active) === false || raw(record.active) === 'false',
+      note: 'Inactive target records may be skipped by the scan engine. Script-only checks do not participate.' };
+  } else target = { kind: 'full', note: 'Instance-wide scans can traverse many tables and take substantially longer.' };
+  if (!target.sys_id && !['full', 'previous'].includes(target.kind)) throw errUsage('The target has no readable sys_id.');
+  const suiteId = argv.suite ? await resolveSuite(sdk, argv.suite) : null;
+  return { target, suite_id: suiteId };
+}
+
+export async function startScan(sdk, plan) {
+  const { target, suite_id: suite } = plan;
+  let response;
+  if (suite && ['update_set', 'scope'].includes(target.kind)) {
+    const kind = target.kind === 'scope' ? 'scoped_apps' : 'update_sets';
+    const field = target.kind === 'scope' ? 'app_scope_sys_ids' : 'update_set_sys_ids';
+    const data = await sdk.request(`${sdk.baseURL}/api/sn_cicd/instance_scan/suite_scan/${requireId(suite, 'suite')}/${kind}`, {
+      method: 'POST', body: JSON.stringify({ [field]: [target.sys_id] }),
+    });
+    response = data?.result;
+    if (response?.error || !['0', '1', '2'].includes(String(response?.status))) throw errAPI(200, 'Scan dispatch was rejected by the provider.');
+    const executionId = response?.links?.progress?.id;
+    if (!isSysId(executionId)) throw errAPI(200, 'Scan dispatch returned no valid execution id. Inspect existing scans before retrying.');
+    return { execution_id: executionId, via: 'sn_cicd', ...plan };
+  }
+  let method, parameters;
+  if (target.kind === 'previous') { method = 'executeScanFromCombo'; parameters = { sysparm_combo_id: target.combo_id }; }
+  else if (suite && target.kind === 'full') { method = 'executeSuiteScan'; parameters = { sysparm_sys_id: suite }; }
+  else if (suite) {
+    method = 'executeSuiteScanWithTargets'; parameters = { sysparm_suite_sys_id: suite,
+      sysparm_target_table: target.table, sysparm_target_sys_ids: JSON.stringify([target.sys_id]) };
+  } else if (target.kind === 'update_set') { method = 'executeUpdateSetScan'; parameters = { sysparm_sys_id: target.sys_id }; }
+  else if (target.kind === 'scope') { method = 'executeAppScan'; parameters = { sysparm_scope_id: target.sys_id }; }
+  else if (target.kind === 'record') { method = 'executePointScan'; parameters = { sysparm_sys_id: target.sys_id, sysparm_table_name: target.table }; }
+  else { method = 'executeFullScan'; parameters = {}; }
+  try { response = JSON.parse(await scanAjax(sdk, method, parameters)); }
+  catch (error) { if (error.code) throw error; throw errAPI(200, 'Malformed scan dispatch answer. Inspect existing scans before retrying.'); }
+  if (response.status !== 0 || !isSysId(response.progressId)) throw errAPI(200, 'Scan dispatch failed or returned no valid execution id. Inspect existing scans before retrying.');
+  return { execution_id: response.progressId, via: 'ScanAjaxProcessor', ...plan };
+}
+
+export async function scanResults(sdk, id, limit = 50) {
+  boundedLimit(limit);
+  const status = await scanStatus(sdk, id);
+  const data = { ...status, checks_executed: null, findings_count: null, checks: [], findings: [],
+    incomplete: !status.terminal, unavailable: [], truncated: {}, rerun_full: false, reusable_target: false };
+  if (!status.result_id) { data.unavailable.push('scan_result'); data.incomplete = true; return data; }
+  let result;
+  try {
+    result = await sdk.get('scan_result', status.result_id);
+    if (!result) throw new Error('Result unavailable');
+    data.scan_number = raw(result.number);
+    const value = raw(result.finding_count);
+    const count = Number(value);
+    if ((typeof value === 'number' || (typeof value === 'string' && /^\d+$/.test(value))) && Number.isInteger(count) && count >= 0) data.findings_count = count;
+    else { data.unavailable.push('scan_result.finding_count'); data.incomplete = true; }
+  } catch { data.unavailable.push('scan_result'); data.incomplete = true; }
+  for (const [key, table, fields] of [
+    ['checks', 'scan_check_execution', ['check', 'message', 'execution_time']],
+    ['findings', 'scan_finding', ['check', 'source_table', 'source', 'finding_details', 'count']],
+  ]) {
+    try {
+      const rows = await sdk.listStrict(table, recordListParams({ limit: limit + 1,
+        query: `result=${status.result_id}^ORDERBYsys_id`, fields, displayValue: 'all' }));
+      data[key] = rows.slice(0, limit);
+      data.truncated[key] = rows.length > limit;
+      if (key === 'checks' && !data.truncated[key] && status.terminal) data.checks_executed = rows.length;
+    } catch { data.unavailable.push(table); data.incomplete = true; }
+  }
+  const comboId = referenceId(result?.combo);
+  if (comboId) {
+    try { const combo = await sdk.get('scan_combo', comboId); if (combo) { data.reusable_target = true; data.rerun_full = !raw(combo.targets); } }
+    catch { /* Optional rerun hint is omitted when target metadata is inaccessible. */ }
+  }
+  data.coverage_note = 'Execution success does not prove functional correctness or complete coverage. Zero findings may mean records or checks were skipped.';
+  return data;
+}
+
+export async function cancelScan(sdk, id) {
+  const status = await scanStatus(sdk, id);
+  if (status.terminal) return { ...status, cancellation_requested: false };
+  const answer = await scanAjax(sdk, 'cancelScan', { sysparm_progress_id: id });
+  const after = await scanStatus(sdk, id);
+  if (after.status !== 'cancelled' && !/cancelled successfully/i.test(answer)) throw errAPI(200, 'Cancellation was not confirmed. Check the execution status before retrying.');
+  return { ...after, cancellation_requested: true };
+}