@jacebenson/jsn 4.3.8 → 4.3.9-dev.62

package/src/commands/actions.js

@@ -9,8 +9,10 @@ import { cancelled, pickDesignerRecord, designerScope, guidedActionCreate, guide
 const ACTION_COMMANDS = [
   { name: 'list', description: 'List actions' },
   { name: 'show [identifier]', description: 'Show an action by name or sys_id' },
+  { name: 'help [identifier]', description: 'Show action input requirements and live usage examples' },
   { name: 'definition [identifier]', description: 'Read the full JSON definition including executable step_instances' },
   { name: 'step-types', description: 'Read step schema templates for a target scope' },
+  { name: 'action-type-schema', description: 'Read provider metadata for an exact action type ID and scope' },
   { name: 'create', description: 'Create an action: guided in a terminal, full JSON definition in scripts' },
   { name: 'update [identifier]', description: 'Save a full definition through Process Flow (alias: edit)' },
   { name: 'test [identifier]', description: 'Execute an action and optionally wait for actual outputs' },
@@ -28,6 +30,53 @@ async function actionID(argv, app) {
   return unwrapSysId(await resolveRecord(app.sdk, { table: ACTION_TABLE, identifier: argv.identifier, matchField: 'name', resource: 'action' }));
 }
 
+const refID = value => typeof value === 'string' ? value : value?.value ?? value?.sys_id ?? value?.sysId ?? value?.id;
+const asBoolean = value => value === true || value === 1 || (typeof value === 'string' && value.toLowerCase() === 'true');
+const EXAMPLE_TYPES = new Set(['approval_rules', 'conditions', 'schedule_date_time']);
+function collectActionExamples(node, snapshotId, allowedInputs, examples, flowName) {
+  if (!node || typeof node !== 'object') return;
+  if (Array.isArray(node)) { for (const item of node) collectActionExamples(item, snapshotId, allowedInputs, examples, flowName); return; }
+  const typeId = refID(node.actionTypeSysId || node.action_type_sys_id || node.actionType || node.action_type);
+  if (typeId === snapshotId && Array.isArray(node.inputs)) {
+    const values = Object.fromEntries(node.inputs.filter(input => input?.name && allowedInputs.has(input.name) && input.value !== undefined && input.value !== null)
+      .map(input => [input.name, refID(input.value) ?? input.value]));
+    if (Object.keys(values).length) examples.push({ flow: flowName, inputs: values });
+  }
+  for (const [key, value] of Object.entries(node)) if (key !== 'inputs') collectActionExamples(value, snapshotId, allowedInputs, examples, flowName);
+}
+async function findActionExamples(sdk, definition, inputDefinitions) {
+  const snapshotId = refID(definition.latest_snapshot);
+  if (!/^[a-f0-9]{32}$/i.test(snapshotId || '')) return { examples: [], status: 'unavailable' };
+  const allowedInputs = new Set(inputDefinitions.filter(input => EXAMPLE_TYPES.has(input.type)
+    && !/(password|secret|token|credential|authorization|cookie|api[_-]?key)/i.test(input.name)).map(input => input.name));
+  if (!allowedInputs.size) return { examples: [], status: 'not_applicable' };
+  const query = new URLSearchParams({
+    sysparm_query: `action_type=${snapshotId}^ORDERBYsys_id`,
+    sysparm_fields: 'sys_id,flow,action_type',
+    sysparm_limit: '20',
+    sysparm_display_value: 'false',
+  });
+  const rows = await sdk.listStrict('sys_hub_action_instance', query);
+  if (!rows.length) return { examples: [], status: 'none' };
+  const flowIds = [...new Set(rows.map(row => refID(row.flow)).filter(value => /^[a-f0-9]{32}$/i.test(value || '')))];
+  if (!flowIds.length) return { examples: [], status: 'unavailable' };
+  const examples = [];
+  let unreadable = false;
+  for (const flowId of flowIds.slice(0, 10)) {
+    try {
+      const result = await sdk.inspectFlow(flowId);
+      const payloadActions = result?.payload?.actionInstances;
+      if (!Array.isArray(payloadActions) || !payloadActions.some(item => item && typeof item === 'object' && !Array.isArray(item))) {
+        unreadable = true;
+        continue;
+      }
+      collectActionExamples(result.payload, snapshotId, allowedInputs, examples, result?.flow?.name || flowId);
+    } catch { unreadable = true; }
+    if (examples.length >= 3) break;
+  }
+  return { examples: examples.slice(0, 3), status: examples.length ? 'found' : unreadable ? 'unavailable' : 'none' };
+}
+
 export const actionsCmd = wrap => {
   // Reuse the existing list/show picker and output contract only.
   const base = buildDevCmd('actions', ACTION_TABLE, ['action'], ['name', 'active', 'sys_scope', 'sys_updated_on'], wrap, {
@@ -55,7 +104,7 @@ export const actionsCmd = wrap => {
     describe: 'Flow Designer actions: create, edit full definitions, and test with outputs',
     builder: y => base.builder(y)
       .command({
-        command: 'create', describe: 'Create parent and executable Process Flow action; verify persistence',
+        command: 'create', describe: 'Create a Process Flow action. Use `jsn actions step-types --scope <sys_id>` for live provider schemas. The required definition structure is code-owned; step-specific fields are provider-defined.',
         builder: yy => dataOptions(yy).option('scope', { type: 'string', describe: 'Exact target scope sys_id, or global' }),
         handler: run(async (argv, app) => {
           const guided = !hasDefinitionData(argv) ? await guidedActionCreate(argv, app) : undefined;
@@ -65,6 +114,27 @@ export const actionsCmd = wrap => {
           app.ok(result, { summary: `Created and verified action ${result.sys_id}` });
         }),
       })
+      .command({
+        command: 'help [identifier]', describe: 'Show action input requirements and examples from flows on this instance',
+        builder: scopeOption,
+        handler: run(async (argv, app) => {
+          const id = await actionID(argv, app);
+          if (id === undefined) return;
+          const scope = await actionScope(app.sdk, id, argv.scope);
+          const definition = await app.sdk.getProcessFlowAction(id, scope);
+          const inputs = (definition.inputs || []).map(input => ({
+            name: input.name,
+            type: input.type || input.parameter?.type || input.parameter?.inputType || input.valueType || 'unknown',
+            mandatory: asBoolean(input.mandatory ?? input.required ?? input.parameter?.mandatory ?? input.parameter?.required),
+            default: input.defaultValue ?? input.default ?? input.parameter?.defaultValue ?? '',
+            description: input.description || input.label || input.parameter?.label || '',
+          }));
+          const exampleResult = await findActionExamples(app.sdk, definition, inputs);
+          app.ok({ action: { id, name: definition.name, scope }, inputs, examples: exampleResult.examples,
+            examples_status: exampleResult.status },
+          { summary: `Input help for action ${definition.name || id}` });
+        }),
+      })
       .command({
         command: 'definition [identifier]', describe: 'Read full JSON definition including executable step_instances',
         builder: scopeOption,
@@ -116,13 +186,30 @@ export const actionsCmd = wrap => {
         }),
       })
       .command({
-        command: 'step-types', describe: 'Read step schema templates for a target scope',
+        command: 'step-types', describe: 'Read full live step schemas for a target scope',
         builder: yy => yy.option('scope', { type: 'string', describe: 'Exact transaction scope sys_id, or global' }),
         handler: run(async (argv, app) => {
           const scope = await designerScope(argv, app);
           app.ok(await app.sdk.getProcessFlowStepTypes(scope), { summary: 'Process Flow step schemas' });
         }),
       })
+      .command({
+        command: 'action-type-schema', describe: 'Read live provider input/output metadata for an exact action type ID and scope',
+        builder: yy => yy.option('id', { type: 'string', demandOption: true, describe: 'Exact 32-character action type sys_id' }).option('scope', { type: 'string', demandOption: true, describe: 'Exact transaction scope sys_id, or global' }),
+        handler: run(async (argv, app) => {
+          if (!/^[a-f\d]{32}$/i.test(argv.id)) throw errUsage('--id must be an exact 32-character action type sys_id');
+          if (!/^(?:[a-fA-F0-9]{32}|global)$/.test(argv.scope)) throw errUsage('--scope must be an exact scope sys_id or global');
+          app.requireInstance();
+          const url = `${app.sdk.baseURL}/api/now/processflow/action/action_types/${encodeURIComponent(argv.id)}?${new URLSearchParams({ sysparm_transaction_scope: argv.scope })}`;
+          const response = await app.sdk.request(url, { method: 'GET' });
+          const result = response?.result;
+          if (response?.error || result?.error || (result?.errorCode !== undefined && result.errorCode !== 0 && result.errorCode !== '0')) {
+            throw new Error(result?.errorMessage || response?.error?.message || 'Provider rejected the action type schema request');
+          }
+          if (!result || typeof result !== 'object') throw new Error('Provider returned no action type metadata');
+          app.ok(result, { summary: `Provider action type schema ${argv.id}` });
+        }),
+      })
       .command({
         command: 'delete [identifier]', describe: 'Delete action parent explicitly',
         builder: yy => scopeOption(yy).option('force', { type: 'boolean', default: false, describe: 'Skip confirmation' }),

package/src/commands/catalog.js

@@ -63,8 +63,8 @@ export function catalogCmd(wrap) {
               for (const v of argv.variable) {
                 const parts = String(v).split(':');
                 if (parts.length >= 2) {
-                  const typeName = parts.length >= 2 ? parts[parts.length - 1] : '';
-                  const label = parts.length >= 3 ? parts[parts.length - 1] : parts[0];
+                  const typeName = parts[1];
+                  const label = parts.length >= 3 ? parts.slice(2).join(':') : parts[0];
                   const sysName = parts[0].replace(/[^a-zA-Z0-9_]/g, '_').toLowerCase();
                   try {
                     await app.sdk.create('item_option_new', {

package/src/commands/customizations.js

@@ -0,0 +1,82 @@
+import { declareCapabilities } from '../capabilities.js';
+import { errUsageHint, errUsage } from '../errors.js';
+import { canUsePicker } from '../helpers.js';
+import { paginatedSearch } from '../paginated-search.js';
+import { captureReport, listReports, getReport, compareReports, formatReport, formatReportList, formatReportComparison } from '../customizations.js';
+import { buildActionableReport, writeCustomizationHtml } from '../customizations-report.js';
+
+// Only capture needs an instance. Saved reports never need network access.
+declareCapabilities('customizations', { noInstance: true, skipDailyChecks: true, mutationSubcommands: [] });
+const listHint = { action: 'list', cmd: 'jsn customizations list', description: 'Browse saved customization captures' };
+const showHint = id => ({ action: 'show', cmd: `jsn customizations show ${id}`, description: 'Review this saved capture' });
+const compareHint = id => ({ action: 'compare', cmd: `jsn customizations compare ${id} OTHER_RUN_ID`, description: 'Compare captured metadata and evidence' });
+function requireReport(id) {
+  const report = getReport(id);
+  if (!report) throw errUsageHint(`Unknown customization report: ${id}`, 'Run `jsn customizations list` to find saved captures.');
+  return report;
+}
+async function pickReport(app, argv, exclude = null, message = 'Select a customization capture') {
+  if (!canUsePicker(app, argv)) throw errUsageHint('A report ID is required when prompts are unavailable.', 'Run `jsn customizations list`, then pass the run ID explicitly.');
+  const runs = listReports({ limit: 1000 }).filter(run => run.run_id !== exclude);
+  if (!runs.length) throw errUsage('No saved customization captures available');
+  const picked = await paginatedSearch({ message, totalCount: runs.length, pageSize: 10, source: async (term = '') => runs.filter(run => `${run.run_id} ${run.label} ${run.instance}`.toLowerCase().includes(term.toLowerCase())).map(run => ({ name: `${run.run_id} ${run.label || '(unlabeled)'} ${run.instance}`, value: run })) });
+  return picked?.value ? requireReport(picked.value.run_id) : null;
+}
+function show(app, report, options = {}) {
+  const actionable = buildActionableReport(report);
+  const triage = actionable.artifacts.map(({ category, category_label, identity, triage: classification }) => ({ category, category_label, identity, ...classification }));
+  app.ok({ ...report, triage, _formatted: formatReport(report, options) }, { summary: `Customization capture ${report.run_id}: ${report.status}`, breadcrumbs: [listHint, showHint(report.run_id), compareHint(report.run_id)] });
+}
+export function customizationsCmd(wrap) {
+  return {
+    command: 'customizations [subcommand]',
+    describe: 'Capture and compare read-only customization evidence locally',
+    builder: y => y
+      .command({ command: 'capture', describe: 'Capture bounded read-only metadata and historical upgrade evidence',
+        builder: b => b.option('label', { type: 'string', describe: 'Label for this capture' })
+          .option('customer-scope', { type: 'string', array: true, default: [], describe: 'Declared customer-owned scope value or sys_id, repeatable; ownership is not inferred' })
+          .option('page-size', { type: 'number', default: 100, describe: 'Records per table page, 1..1000' })
+          .option('max-pages', { type: 'number', default: 10, describe: 'Maximum pages per source, 1..100' }),
+        handler: wrap(async (argv, app) => {
+          app.requireInstance();
+          if (!Number.isInteger(argv.pageSize) || argv.pageSize < 1 || argv.pageSize > 1000 || !Number.isInteger(argv.maxPages) || argv.maxPages < 1 || argv.maxPages > 100) throw errUsage('page-size must be 1..1000 and max-pages 1..100');
+          const customerScopes = Array.isArray(argv.customerScope) ? argv.customerScope : argv.customerScope ? [argv.customerScope] : [];
+          const report = await captureReport({ sdk: app.sdk, instance: app.getEffectiveInstance(), profile: app.session?.profileName || '', label: argv.label || '', customerScopes, pageSize: argv.pageSize, maxPages: argv.maxPages });
+          show(app, report);
+        }),
+      })
+      .command({ command: 'list', aliases: ['ls'], describe: 'List saved local captures',
+        builder: b => b.option('limit', { alias: 'l', type: 'number', default: 50, describe: 'Maximum captures to list' }),
+        handler: wrap(async (argv, app) => {
+          if (canUsePicker(app, argv)) { const report = await pickReport(app, argv); if (report) show(app, report); return; }
+          const runs = listReports({ limit: argv.limit });
+          app.ok({ runs, count: runs.length, _formatted: formatReportList(runs) }, { summary: `${runs.length} customization capture(s)`, breadcrumbs: [listHint, ...(runs[0] ? [showHint(runs[0].run_id)] : [])] });
+        }),
+      })
+      .command({ command: 'show [run_id]', describe: 'Review a saved capture offline', builder: b => b
+        .option('group-by', { type: 'string', choices: ['type', 'scope', 'updated-by'], default: 'type', describe: 'Group summary by file type, scope or last updater' })
+        .option('filter', { type: 'string', describe: 'Expand a group shown in the summary (friendly or table name for file types)' }), handler: wrap(async (argv, app) => {
+        const report = argv.run_id ? requireReport(argv.run_id) : await pickReport(app, argv);
+        if (report) show(app, report, { groupBy: argv.groupBy, filter: argv.filter || '' });
+      }) })
+      .command({ command: 'html [run_id]', describe: 'Write a searchable, self-contained HTML review of a saved capture', builder: b => b
+        .option('out', { type: 'string', describe: 'Output HTML path (must not already exist)' }), handler: wrap(async (argv, app) => {
+        const report = argv.run_id ? requireReport(argv.run_id) : await pickReport(app, argv);
+        if (!report) return;
+        const file = writeCustomizationHtml(report, { out: argv.out });
+        app.ok({ run_id: report.run_id, file, artifacts: Object.values(report.categories).reduce((total, items) => total + items.length, 0) }, { summary: `Wrote offline customization review: ${file}`, breadcrumbs: [listHint, showHint(report.run_id)] });
+      }) })
+      .command({ command: 'compare [baseline] [new]', describe: 'Compare two saved captures from the same instance', handler: wrap(async (argv, app) => {
+        if (!!argv.baseline !== !!argv.new) throw errUsage('Compare requires exactly two report IDs');
+        if (argv.baseline && argv.baseline === argv.new) throw errUsage('Compare requires two different report IDs');
+        const baseline = argv.baseline ? requireReport(argv.baseline) : await pickReport(app, argv, null, 'Select the baseline capture');
+        if (!baseline) return;
+        const newer = argv.new ? requireReport(argv.new) : await pickReport(app, argv, baseline.run_id, 'Select the new capture');
+        if (!newer) return;
+        if (baseline.instance !== newer.instance) throw errUsage('Customization reports must describe the same instance');
+        const result = compareReports(baseline, newer);
+        app.ok({ ...result, _formatted: formatReportComparison(result) }, { summary: `Customization comparison: ${result.status}`, breadcrumbs: [listHint, showHint(baseline.run_id), showHint(newer.run_id)] });
+      }) }),
+    handler: wrap(async (_argv, app) => app.ok({ command: 'customizations', subcommands: ['capture', 'list', 'show', 'html', 'compare'] }, { summary: 'Use `jsn customizations <subcommand> --help` for details.' })),
+  };
+}

package/src/commands/flows.js

@@ -6,7 +6,7 @@ import { inspectFlow } from '../flow-inspection.js';
 import { publishFlows, publishFlowLifecycle, publishDoctor, flowStatus } from '../flow-publish.js';
 import { resolveRecord, unwrapSysId } from '../resolve-record.js';
 import { createFlowFromManifest, updateFlowFromManifest, readCurrentUpdateSet } from '../flow-create.js';
-import { EXCLUDED_TRIGGER_TYPES, SUPPORTED_TRIGGER_TYPES } from '../flow-triggers.js';
+import { EXCLUDED_TRIGGER_TYPES, SUPPORTED_TRIGGER_TYPES, readTriggerCatalog, readTriggerInputDefinitions } from '../flow-triggers.js';
 import { testFlow } from '../flow-test.js';
 import { errUsage } from '../errors.js';
 import { cancelled, pickDesignerRecord, guidedFlowCreate, guidedFlowEdit, guidedFlowTestRecord, hasDefinitionData, confirmDesignerMutation } from '../flow-designer-interactive.js';
@@ -63,6 +63,25 @@ export function flowsCmd(wrap) {
     describe: 'Manage Flow Designer flows',
     builder: (yargs) => {
       return yargs
+        .command({
+          command: 'schemas',
+          describe: 'Read live trigger catalog and declared inputs; supported marks verified CLI creation families',
+          handler: wrap(async (_argv, app) => {
+            app.requireInstance();
+            const catalog = await readTriggerCatalog(app.sdk);
+            for (const category of catalog.categories) {
+              for (const trigger of category.triggers) {
+                if (trigger.supported) trigger.inputs = await readTriggerInputDefinitions(app.sdk, trigger.sysId);
+              }
+            }
+            for (const trigger of catalog.ungrouped) {
+              if (trigger.supported) trigger.inputs = await readTriggerInputDefinitions(app.sdk, trigger.sysId);
+            }
+            const data = { ...catalog, structural_contract: 'Manifest keys and persistence shape are code-owned; trigger definitions and input metadata are instance-derived.' };
+            data._formatted = [...catalog.categories.flatMap(c => c.triggers.map(t => `${c.name}: ${t.name} [${t.type}] ${t.supported ? 'supported' : 'not supported'}; inputs: ${(t.inputs || []).map(i => i.name + ':' + i.type).join(', ')}`)), ...catalog.ungrouped.map(t => `${t.name} [${t.type}] ungrouped${t.supported ? '; supported' : '; not supported'}; inputs: ${(t.inputs || []).map(i => i.name + ':' + i.type).join(', ')}`)].join('\n');
+            app.ok(data, { summary: 'Live Flow trigger schemas' });
+          }),
+        })
         .command({
           command: 'list',
           aliases: ['ls'],
@@ -294,7 +313,7 @@ export function flowsCmd(wrap) {
         })
         .command({
           command: 'create',
-          describe: 'Create a draft flow: pick a trigger category then trigger in a terminal, or use a JSON manifest in scripts',
+          describe: 'Create a draft flow from a JSON manifest or guided prompts. Use `jsn flows schemas` for instance-derived trigger and input schemas, and `jsn actions action-type-schema --id <actionTypeId> --scope <scopeId>` for provider action inputs. Manifest structure remains code-owned.',
           builder: (y) => y
             .option('data', { type: 'string', describe: 'Flow manifest as inline JSON' })
             .option('data-file', { type: 'string', describe: 'Read the flow manifest from a JSON file' })
@@ -322,10 +341,11 @@ export function flowsCmd(wrap) {
         .command({
           command: 'update [identifier]',
           aliases: ['edit'],
-          describe: 'Safely update supported fields of an existing inactive Draft flow',
+          describe: 'Save partial edits to an inactive Draft: record_create_or_update trigger table/condition and existing action inputs. Use --preview for before/after values without writes. Published checkout, Flow Logic, variables, catalog-trigger edits and stage placement require Flow Designer. Never publishes or executes. Use `jsn flows schemas` and `jsn actions action-type-schema --id <actionTypeId> --scope <scopeId>` for live schemas; omitted values are preserved.',
           builder: (y) => y
             .option('data', { type: 'string', describe: 'Update manifest as inline JSON' })
             .option('data-file', { type: 'string', describe: 'Read the update manifest from a JSON file' })
+            .option('preview', { type: 'boolean', default: false, describe: 'Validate and show exact before/after input values without saving or versioning' })
             .option('force', { type: 'boolean', default: false, describe: 'Skip confirmation' }),
           handler: wrap(async (argv, app) => {
             app.requireInstance();
@@ -341,12 +361,14 @@ export function flowsCmd(wrap) {
             } catch (error) {
               throw new Error(`Invalid flow update manifest JSON: ${error.message}`, { cause: error });
             }
-            await confirmDesignerMutation(argv, app, `Update draft flow ${identifier}; unspecified components and inputs are preserved`);
+            if (!argv.preview) await confirmDesignerMutation(argv, app, `Update draft flow ${identifier}; unspecified components and inputs are preserved`);
             const result = await updateFlowFromManifest(app.sdk, app.getEffectiveInstance(), argv.identifier, manifest, {
+              preview: argv.preview,
               readUpdateSet: () => readCurrentUpdateSet(app.sdk),
             });
-            return app.ok(result, {
-              summary: `Updated draft flow "${result.flow.name}" (${result.flow.id}) without activation`,
+            const diff = result.changes.map(change => `${change.component}${change.order ? ` ${change.order}` : ''}.${change.input}: ${JSON.stringify(change.before)} -> ${JSON.stringify(change.after)}`).join('\n');
+            return app.ok({ ...result, _formatted: diff }, {
+              summary: `${result.preview ? 'Preview for' : 'Updated'} draft flow "${result.flow.name}" (${result.flow.id}) without activation`,
               breadcrumbs: [{ action: 'show', cmd: `jsn flows show ${result.flow.id}`, description: 'Inspect the updated draft flow' }],
             });
           }),

package/src/commands/skipped-updates.js

@@ -0,0 +1,102 @@
+import { checkbox, select, confirm } from '@inquirer/prompts';
+import { canUsePicker, interactiveList, getStringField } from '../helpers.js';
+import { declareCapabilities } from '../capabilities.js';
+import { errUsage } from '../errors.js';
+import { discoverSkippedUpdates, reviewSkippedUpdate, prepareSkippedBatch, processSkippedBatch, raw, SKIP_TABLE } from '../skipped-updates.js';
+
+const label = row => `${raw(row.sys_id)}  ${getStringField(row, 'target_name') || getStringField(row, 'file_name')}`;
+const selectionOptions = y => y
+  .option('ids', { type: 'string', describe: 'Comma-separated literal finding sys_ids, maximum 100' })
+  .option('action', { type: 'string', choices: ['retain', 'revert'], describe: 'Explicit selected action, never inferred from recommendations' });
+
+export function renderSkippedPreview(preview) {
+  const lines = [`Instance: ${preview.instance}`, `Exact selected batch: ${preview.count} finding(s)`];
+  for (const item of preview.selected) {
+    lines.push(`\n${item.sys_id}: ${item.artifact.update_name}`, `Action: ${item.action}`, item.operation,
+      `Recommendation only: ${item.impact.recommendation.action}. ${item.impact.recommendation.basis}`,
+      `State: disposition=${item.finding.disposition}, resolution=${item.finding.resolution_status}`,
+      `Evidence: base version ${item.impact.evidence.baseline_version || 'unknown'}, source ${item.impact.evidence.baseline_source_table || 'unknown'}/${item.impact.evidence.baseline_source || 'unknown'}`,
+      `Finding: ${preview.instance}/${SKIP_TABLE}.do?sys_id=${item.sys_id}`,
+      item.impact.direct_behavior.summary);
+    for (const change of item.impact.changes) lines.push(`  ${change.field}: ${JSON.stringify(change.current)} -> ${JSON.stringify(change.base)}`, `  ${change.effect}`);
+    for (const dep of item.impact.known_dependencies) lines.push(`  Known dependency: ${dep.table}.${dep.field} / ${dep.sys_id}`);
+    for (const gap of item.impact.unknown) lines.push(`  Unknown: ${gap}`);
+  }
+  lines.push(`\nConfirmation token: ${preview.confirmation_token}`, 'No writes have been performed.');
+  return lines.join('\n');
+}
+
+export function skippedUpdatesCmd(wrap, ui = {}) {
+  declareCapabilities('skipped-updates', { mutationSubcommands: ['process'] });
+  const prompts = { checkbox, select, confirm, canUsePicker, interactiveList, ...ui };
+  async function showReview(app, id) {
+    const review = await reviewSkippedUpdate(app.sdk, id);
+    const display = { instance: app.getEffectiveInstance(), selected: [{ ...review, action: 'none', operation: 'Read-only review.' }], count: 1, confirmation_token: 'not applicable' };
+    app.ok({ ...review, _formatted: renderSkippedPreview(display) }, { summary: 'Skipped update review; deeper effects remain unknown' });
+  }
+  async function selection(argv, app, guided) {
+    let ids = typeof argv.ids === 'string' ? argv.ids.split(',') : undefined;
+    let action = argv.action;
+    if (!ids && guided) {
+      const page = await discoverSkippedUpdates(app.sdk, { limit: 100, offset: 0 });
+      if (!page.count) throw errUsage('No unresolved skipped findings were returned.');
+      ids = await prompts.checkbox({ message: `Select findings from this page${page.has_more ? ' (more exist; use list --offset for others)' : ''}`,
+        choices: page.findings.map(row => ({ name: label(row), value: raw(row.sys_id) })), required: true });
+    }
+    if (!ids?.length) throw errUsage('Provide --ids with the exact selected finding sys_ids.');
+    if (!action && guided) action = await prompts.select({ message: 'Choose the action for these findings',
+      choices: [{ name: 'Retain customization, mark reviewed and retained', value: 'retain' },
+        { name: 'Return to base system, discard customization', value: 'revert' }] });
+    return { ids, action, instance: app.getEffectiveInstance() };
+  }
+  return { command: 'skipped-updates', describe: 'Review and process existing unresolved skipped updates across all upgrade history',
+    builder: y => y
+      .command({ command: 'list', describe: 'Discover unresolved skips instance-wide, independent of new upgrades',
+        builder: y => y.option('limit', { type: 'number', default: 100, describe: 'Page size, maximum 500' })
+          .option('offset', { type: 'number', default: 0, describe: 'Page offset' }),
+        handler: wrap(async (argv, app) => {
+          app.requireInstance();
+          if (prompts.canUsePicker(app, argv)) {
+            const selected = await prompts.interactiveList({ app, table: SKIP_TABLE, singular: 'skipped update',
+              columns: ['target_name', 'file_name', 'disposition', 'resolution_status'], labelField: 'target_name',
+              query: 'dispositionIN4,104,9,10,11^resolution_statusIN,not_reviewed', formatLabel: label });
+            if (selected === undefined) return;
+            if (selected) { await showReview(app, raw(selected.sys_id)); return; }
+          }
+          const page = await discoverSkippedUpdates(app.sdk, argv);
+          app.ok(page, { summary: `${page.count} unresolved finding(s) fetched${page.has_more ? '; more available' : ''}. Instance-wide total is not measured.` });
+        }) })
+      .command({ command: 'review <sys-id>', describe: 'Review artifact evidence, field changes and bounded known dependencies',
+        handler: wrap(async (argv, app) => { app.requireInstance();
+          await showReview(app, argv['sys-id']);
+        }) })
+      .command({ command: 'preview', describe: 'Read-only exact batch preview and confirmation token', builder: selectionOptions,
+        handler: wrap(async (argv, app) => { app.requireInstance();
+          const options = await selection(argv, app, prompts.canUsePicker(app, argv));
+          const preview = await prepareSkippedBatch(app.sdk, options);
+          app.ok({ ...preview, _formatted: renderSkippedPreview(preview) }, { summary: 'Read-only batch preview; review before confirming' });
+        }) })
+      .command({ command: 'process', describe: 'Apply selected action after ONE explicit confirmation of the exact preview',
+        builder: y => selectionOptions(y).option('confirm', { type: 'string', describe: 'Confirmation token from a previously reviewed exact preview; required in automation' }),
+        handler: wrap(async (argv, app) => { app.requireInstance();
+          try {
+            const guided = prompts.canUsePicker(app, argv);
+            const options = await selection(argv, app, guided);
+            const result = await processSkippedBatch({ sdk: app.sdk, ...options,
+              readOnly: app.session?.readOnly === true, confirmationToken: argv.confirm,
+              onPreview: guided ? async preview => app.ok({ ...preview, _formatted: renderSkippedPreview(preview) }, { summary: 'Review exact batch before confirmation' }) : undefined,
+              confirm: guided && !argv.confirm ? async () => prompts.confirm({ message: 'Apply exactly this selected batch?', default: false }) : undefined });
+            app.ok({ ...result, _formatted: result.cancelled ? 'Cancelled. No writes performed.'
+              : result.results.map(row => `${row.sys_id} ${row.action}: ${row.success ? 'verified success' : `FAILED (${row.effect})`}`).join('\n') },
+            { summary: `${result.success_count} succeeded; ${result.failure_count} failed${result.partial ? '; partial batch' : ''}` });
+            if (result.failure_count) process.exitCode = 1;
+          } catch (err) {
+            if (err.name === 'ExitPromptError' || err.name === 'AbortPromptError') {
+              app.ok({ cancelled: true, writes_performed: false }, { summary: 'Cancelled. No writes performed.' }); return;
+            }
+            throw err;
+          }
+        }) })
+      .demandCommand(1, 'Choose list, review, preview or process'),
+  };
+}

package/src/commands/updatesets.js

@@ -1,7 +1,10 @@
 import fs from 'node:fs';
-import { formatRecordForDisplay, getStringField, interactiveList, assertSafeExactMatch } from '../helpers.js';
+import { editor, confirm } from '@inquirer/prompts';
+import { formatRecordForDisplay, getStringField, interactiveList, assertSafeExactMatch, canPrompt, buildRerunCommand, verifyWriteBack } from '../helpers.js';
+import { getActiveProfile } from '../config.js';
+import { FormatAuto } from '../output.js';
 import { getCurrentApplication, getCurrentUpdateSet, requireCurrentUserSysId, setCurrentApplication, setCurrentUpdateSet } from '../context.js';
-import { errAPI, errUsage } from '../errors.js';
+import { errAPI, errUsage, errConfirmationRequired } from '../errors.js';
 import { declareCapabilities } from '../capabilities.js';
 
 declareCapabilities('updatesets', {
@@ -133,6 +136,28 @@ async function fetchUpdateSetById(app, sysID) {
   return Array.isArray(records) && records.length > 0 ? records[0] : null;
 }
 
+/** Completion refuses duplicate names rather than guessing a mutation target. */
+async function resolveCompletionTarget(app, name) {
+  if (name !== undefined) {
+    if (!String(name).trim()) throw errUsage('Update set name must not be empty');
+    assertSafeExactMatch(name);
+    const params = new URLSearchParams({
+      sysparm_query: `name=${name}`, sysparm_limit: '2',
+      sysparm_display_value: 'all', sysparm_fields: 'sys_id,name',
+    });
+    const records = await app.sdk.list('sys_update_set', params);
+    if (!records.length) throw errUsage(`Update set not found: ${name}`);
+    if (records.length !== 1) {
+      throw errUsage(`Multiple update sets named "${name}". Select the intended set with "jsn updatesets set", then run "jsn updatesets complete" without a name.`);
+    }
+    return { sys_id: rawReferenceId(records[0].sys_id), name: getStringField(records[0], 'name') };
+  }
+  const userSysID = await requireCurrentUserSysId(app.sdk);
+  const current = await getCurrentUpdateSet(app.sdk, userSysID);
+  if (!current?.sys_id) throw errUsage('No current update set. Set one first:\n  jsn updatesets set');
+  return current;
+}
+
 /** Build a safe, flat preorder hierarchy with ancestors before the selected set. */
 export async function buildUpdateSetHierarchy(app, selectedRecord) {
   const selectedID = getStringField(selectedRecord, 'sys_id');
@@ -535,25 +560,16 @@ export function updateSetsCmd(wrap) {
               throw errUsage(`Cannot set "${name}" as current — update set is ${stateRaw === 'ignore' ? 'ignored' : 'complete'}.\nView it instead: jsn updatesets show "${name}"`);
             }
             const userSysID = await requireCurrentUserSysId(app.sdk);
-            await setCurrentUpdateSet(app.sdk, userSysID, sysID);
-
-            // Like the platform update set picker: switching the set also
-            // switches the application scope into the set's scope. The
-            // application field is a sys_scope reference, so its raw value
-            // IS the scope sys_id the apps.current_app preference stores.
+            // Scope selection can reset the session's capture set. Select the
+            // scope first, then the requested set, and verify both picker writes.
+            const scopeSysId = updateSetApp?.value || (typeof updateSetApp === 'string' ? updateSetApp : '');
             let scopeNote = '';
-            try {
-              const scopeSysId = updateSetApp?.value || (typeof updateSetApp === 'string' ? updateSetApp : '');
-              if (scopeSysId) {
-                await setCurrentApplication(app.sdk, userSysID, scopeSysId);
-                const scopeName = updateSetApp?.display_value || updateSetApp;
-                scopeNote = ` — scope switched to ${scopeName}`;
-              }
-            } catch {
-              // scope switch failed — fall back to a warning
-              const currentApp = await getCurrentApplication(app.sdk, userSysID).catch(() => null);
-              scopeNote = scopeMismatchWarning(updateSetApp, currentApp);
+            if (scopeSysId) {
+              await setCurrentApplication(app.sdk, userSysID, scopeSysId);
+              const scopeName = updateSetApp?.display_value || updateSetApp;
+              scopeNote = ` — scope switched to ${scopeName}`;
             }
+            await setCurrentUpdateSet(app.sdk, userSysID, sysID);
 
             app.ok({ update_set: name, sys_id: sysID }, { summary: `Current update set: ${name}${scopeNote}` });
           }),
@@ -606,15 +622,18 @@ export function updateSetsCmd(wrap) {
 
             // Auto-set as current update set
             const sysID = record?.sys_id?.value || record?.sys_id;
+            let selectionNote = '';
             try {
               const userSysID = await requireCurrentUserSysId(app.sdk);
               await setCurrentUpdateSet(app.sdk, userSysID, sysID);
-            } catch {
-              // Non-fatal — auto-set is a convenience, not mandatory
+            } catch (error) {
+              // Creation succeeded. Report partial success without hiding a
+              // failed selection or inviting a duplicate create on retry.
+              selectionNote = `; not selected as current: ${error.message}. Run jsn updatesets set "${argv.name}"`;
             }
 
             app.ok(record, {
-              summary: `Created update set: ${argv.name}`,
+              summary: `Created update set: ${argv.name}${selectionNote}`,
               breadcrumbs: [
                 {
                   action: 'set',
@@ -631,16 +650,57 @@ export function updateSetsCmd(wrap) {
           }),
         })
         .command({
-          command: 'complete',
-          describe: 'Mark the current update set as complete',
+          command: 'complete [name]',
+          describe: 'Complete a named or current update set with completion notes',
+          builder: (y) => y
+            .positional('name', { type: 'string', describe: 'Unique update set name, defaults to the current set' })
+            .option('notes', { type: 'string', describe: 'Completion notes, one bullet per line; opens an editor when omitted interactively' }),
           handler: wrap(async (argv, app) => {
-            const userSysID = await requireCurrentUserSysId(app.sdk);
-            const current = await getCurrentUpdateSet(app.sdk, userSysID);
-            if (!current?.sys_id) {
-              throw errUsage('No current update set. Set one first:\n  jsn updatesets set');
+            const current = await resolveCompletionTarget(app, argv.name);
+            const record = await fetchUpdateSetById(app, current.sys_id);
+            if (!record) throw errUsage(`Update set not found or unreadable: ${current.sys_id}`);
+            if (!Object.hasOwn(record, 'description')
+              || (record.description && typeof record.description === 'object' && !Object.hasOwn(record.description, 'value'))) {
+              throw errUsage(`Description is unreadable for update set "${current.name}" (${current.sys_id}); refusing to replace unknown text.`);
+            }
+            const existing = String(record.description && typeof record.description === 'object'
+              ? record.description.value ?? '' : record.description ?? '');
+            const interactive = !argv.json && !argv.get && (!argv.format || argv.format === FormatAuto)
+              && app.output?.getFormat() === FormatAuto && canPrompt();
+            let notes = argv.notes;
+            let description;
+            try {
+              if (notes === undefined) {
+                if (!interactive) throw errUsage('Provide nonempty completion notes with --notes in noninteractive mode');
+                notes = await editor({ message: `Completion notes for "${current.name}". Write concise bullets, one per line` });
+              }
+              const bullets = String(notes).split(/\r?\n/)
+                .map(line => line.trim().replace(/^[-*•]\s*/, '').trim()).filter(Boolean)
+                .map(line => `- ${line}`).join('\n');
+              if (!bullets) throw errUsage('Provide nonempty completion notes with --notes');
+              description = existing ? `${existing}\n\n${bullets}` : bullets;
+              if (existing && !argv.force && getActiveProfile(app.config)?.skip_confirmations !== true) {
+                const question = `Append notes and complete "${current.name}"?\nExisting Description:\n${existing}\n\nNew notes:\n${bullets}`;
+                if (!interactive) throw errConfirmationRequired(question, buildRerunCommand(argv, {
+                  rerun: ['updatesets', 'complete', ...(argv.name !== undefined ? [argv.name] : []), '--notes', String(notes)],
+                }));
+                if (!await confirm({ message: question, default: false })) return;
+              }
+            } catch (error) {
+              if (['ExitPromptError', 'AbortPromptError'].includes(error.name)) return;
+              throw error;
+            }
+            const data = { state: 'complete', description };
+            try {
+              await app.sdk.update('sys_update_set', current.sys_id, data);
+            } catch (error) {
+              throw errAPI(error.status || 0, `Could not complete update set "${current.name}" (${current.sys_id}): ${error.message}. Check the record before retrying.`);
+            }
+            const mismatches = await verifyWriteBack(app, 'sys_update_set', current.sys_id, data);
+            if (mismatches.length) {
+              throw errAPI(200, `Could not verify completion of update set "${current.name}" (${current.sys_id}): ${mismatches.map(item => item.field).join(', ')} did not persist or could not be read. The write may have partially succeeded; inspect the set before retrying.`);
             }
-            await app.sdk.update('sys_update_set', current.sys_id, { state: 'complete' });
-            app.ok({ update_set: current.name, state: 'complete' }, { summary: `Update set marked complete: ${current.name}` });
+            app.ok({ update_set: current.name, sys_id: current.sys_id, state: 'complete', description }, { summary: `Update set marked complete: ${current.name}` });
           }),
         })
         .command({
@@ -667,7 +727,7 @@ export function updateSetsCmd(wrap) {
         console.log('  export <name>  Export an update set to XML (stdout or --out)');
         console.log('  set  [name]    Set the current update set (picker when run bare)');
         console.log('  create         Create a new update set (auto-sets as current)');
-        console.log('  complete       Mark the current update set as complete');
+        console.log('  complete [name] Complete a named or current set with --notes (editor when omitted)');
         console.log('  ignore         Ignore the current update set');
         console.log('  parent <name>  Set the parent of an update set');
         console.log('\nRun "jsn updatesets <command> --help" for details.');