@jacebenson/jsn 4.3.8 → 4.3.9

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.');

package/src/context.js

@@ -63,25 +63,16 @@ export async function getCurrentUpdateSet(sdk, userSysID) {
   return { name: val, sys_id: val };
 }
 
-/**
- * Find-or-create a sys_user_preference and set its value. Shared by the
- * scope/update-set "set" commands and create auto-set (was copy-pasted 3x).
- */
-async function setUserPreference(sdk, userSysID, name, value) {
-  const params = new URLSearchParams();
-  params.set('sysparm_query', `user=${userSysID}^name=${name}`);
-  params.set('sysparm_limit', '1');
-  params.set('sysparm_fields', 'sys_id');
-  const prefs = await sdk.list('sys_user_preference', params);
-  if (prefs.length > 0) {
-    await sdk.update('sys_user_preference', getStringField(prefs[0], 'sys_id'), { value });
-  } else {
-    await sdk.create('sys_user_preference', {
-      user: userSysID,
-      name,
-      value,
-      type: 'string',
-    });
+// Use the same selection contract as the platform picker. Table API writes to
+// sys_user_preference do not update an already-warmed session's capture context.
+async function selectContext(sdk, picker, data, expected) {
+  const endpoint = `${sdk.baseURL}/api/now/ui/concoursepicker/${picker}`;
+  await sdk.request(endpoint, { method: 'PUT', body: JSON.stringify(data) });
+  const response = await sdk.request(endpoint, { method: 'GET' });
+  const current = response?.result?.current;
+  const actual = picker === 'application' ? current : current?.sysId;
+  if (actual !== expected) {
+    throw new Error(`${picker === 'application' ? 'Application' : 'Update set'} selection was not applied. Expected ${expected}, received ${typeof actual === 'string' ? actual : 'an unreadable selection'}.`);
   }
 }
 
@@ -98,12 +89,12 @@ export async function requireCurrentUserSysId(sdk) {
   return getStringField(user[0], 'sys_id');
 }
 
-/** Set the current application scope via the apps.current_app preference. */
-export async function setCurrentApplication(sdk, userSysID, scopeSysID) {
-  await setUserPreference(sdk, userSysID, 'apps.current_app', scopeSysID);
+/** Select application scope in the authenticated session and verify it. */
+export async function setCurrentApplication(sdk, _userSysID, scopeSysID) {
+  await selectContext(sdk, 'application', { app_id: scopeSysID }, scopeSysID);
 }
 
-/** Set the current update set via the sys_update_set preference. */
-export async function setCurrentUpdateSet(sdk, userSysID, updateSetSysID) {
-  await setUserPreference(sdk, userSysID, 'sys_update_set', updateSetSysID);
+/** Select the capture update set in the authenticated session and verify it. */
+export async function setCurrentUpdateSet(sdk, _userSysID, updateSetSysID) {
+  await selectContext(sdk, 'updateset', { sysId: updateSetSysID }, updateSetSysID);
 }

package/src/customizations-report.js

@@ -0,0 +1,158 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const CLASSIFICATIONS = {
+  ootb_modifications: {
+    label: 'Historical upgrade skip',
+    confidence: 'Historical evidence only',
+    summary: 'An upgrade record says the platform preserved this artifact. That does not prove it currently differs from the vendor version.',
+    next_steps: [
+      'Compare the current artifact with a trusted baseline for this exact release.',
+      'Review later update-set history for a merge, reversion, or further edit.',
+      'Check callers and add a regression test in non-production before considering a revert.',
+    ],
+  },
+  customer_app_artifacts: {
+    label: 'Caller-declared customer scope',
+    confidence: 'Declaration, not verified ownership',
+    summary: 'The scope record matched a scope declared by the person who captured this report. The instance does not verify customer or publisher ownership.',
+    next_steps: [
+      'Confirm the application owner and publisher with the responsible team.',
+      'Check whether the artifact is active or referenced, then review its tests and update-set history.',
+      'Treat it as customer-owned only after an owner confirms the declaration.',
+    ],
+  },
+  unclassified: {
+    label: 'Unclassified metadata',
+    confidence: 'Insufficient evidence',
+    summary: 'Visible metadata was found, but this capture could not establish whether it is customer-owned or differs from an out-of-box artifact.',
+    next_steps: [
+      'Identify the owner using application records, update-set history, and team knowledge.',
+      'Check current references and expected behavior before changing or deleting it.',
+      'Compare with a trusted vendor baseline only when evidence shows this is vendor-delivered.',
+    ],
+  },
+};
+
+const humanize = value => String(value || '').replace(/^sys_/, '').replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2').replace(/([a-z0-9])([A-Z])/g, '$1 $2').replaceAll('_', ' ').replace(/\bui\b/gi, 'UI').replace(/\b[a-z]/g, letter => letter.toUpperCase());
+const categoryLabel = category => ({ ootb_modifications: 'Historical upgrade skips', customer_app_artifacts: 'Declared customer scopes', unclassified: 'Unclassified metadata' })[category] || humanize(category);
+const itemName = item => {
+  const { name = '', update_name: updateName = '', table = '', sys_id: sysId = '' } = item.identity || {};
+  if (name && name !== sysId && name !== updateName) return /[_]|[a-z][A-Z]/.test(name) ? humanize(name) : name;
+  if (updateName) {
+    const prefixes = [table, table.replace(/_[^_]+$/, ''), table.replace(/_[^_]+_[^_]+$/, '')].filter(Boolean);
+    const prefix = prefixes.find(candidate => updateName.startsWith(`${candidate}_`));
+    return humanize(prefix ? updateName.slice(prefix.length + 1) : updateName) || 'Name unavailable';
+  }
+  return sysId ? 'Name unavailable' : 'Unnamed artifact';
+};
+
+export function classifyCustomization(category) {
+  const classification = CLASSIFICATIONS[category] || CLASSIFICATIONS.unclassified;
+  return {
+    code: CLASSIFICATIONS[category] ? category : 'unclassified',
+    label: classification.label,
+    confidence: classification.confidence,
+    summary: classification.summary,
+    next_steps: [...classification.next_steps],
+    // There is no verified baseline or dependency graph to support safe automatic remediation.
+    automated_remediation: false,
+  };
+}
+
+function recordUrl(instance, table, sysId) {
+  if (!/^[a-z0-9_]+$/i.test(String(table || '')) || !sysId) return null;
+  try {
+    const url = new URL(`${encodeURIComponent(table)}.do`, `${String(instance).replace(/\/+$/, '')}/`);
+    if (!['http:', 'https:'].includes(url.protocol)) return null;
+    url.searchParams.set('sys_id', String(sysId));
+    return url.href;
+  } catch {
+    return null;
+  }
+}
+
+export function buildActionableReport(report) {
+  const artifacts = Object.entries(report.categories || {}).flatMap(([category, items]) => items.map(item => ({
+    category,
+    category_label: categoryLabel(category),
+    identity: item.identity || {},
+    name: itemName(item),
+    table_label: humanize(item.identity?.table || 'unknown'),
+    scope: item.scope?.scope || item.scope?.sys_id || '(unknown scope)',
+    updated_by: item.identity?.updated_by || '(unknown updater)',
+    evidence: item.evidence || [],
+    risk: item.risk || { rating: 'unknown', rationale: 'Risk has not been established.' },
+    triage: classifyCustomization(category),
+    record_url: recordUrl(report.instance, item.identity?.table, item.identity?.sys_id),
+  })));
+  return {
+    run_id: report.run_id,
+    label: report.label || '',
+    instance: report.instance,
+    status: report.status,
+    start_time: report.start_time,
+    artifacts,
+    coverage: report.coverage,
+  };
+}
+
+const safeJson = value => JSON.stringify(value).replace(/[<>&\u2028\u2029]/g, character => ({ '<': '\\u003c', '>': '\\u003e', '&': '\\u0026', '\u2028': '\\u2028', '\u2029': '\\u2029' })[character]);
+const escapeHtml = value => String(value ?? '').replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;').replaceAll("'", '&#39;');
+
+export function renderCustomizationHtml(report) {
+  const view = buildActionableReport(report);
+  const categoryOptions = [...new Set(view.artifacts.map(item => item.category))].map(category => `<option value="${escapeHtml(category)}">${escapeHtml(categoryLabel(category))}</option>`).join('');
+  const data = safeJson(view);
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Customization review${view.label ? `: ${escapeHtml(view.label)}` : ''}</title>
+<style>
+:root{color-scheme:light;--ink:#202833;--muted:#526173;--line:#d8dee7;--panel:#fff;--wash:#f3f6fa;--blue:#1358a5;--amber:#825300}*{box-sizing:border-box}body{margin:0;background:var(--wash);color:var(--ink);font:16px/1.5 system-ui,sans-serif}main{max-width:1180px;margin:auto;padding:32px 20px 60px}h1,h2,h3,p{margin-top:0}h1{font-size:1.8rem;margin-bottom:4px}h2{font-size:1.25rem;margin:0 0 14px}h3{font-size:1.1rem;margin:0}small,.muted{color:var(--muted)}.intro,.toolbar,.coverage,.group,.card{background:var(--panel);border:1px solid var(--line);border-radius:10px}.intro,.toolbar,.coverage{padding:18px 20px;margin-bottom:16px}.intro p:last-child{margin-bottom:0}.stats{display:flex;flex-wrap:wrap;gap:10px;margin-top:14px}.stat{background:var(--wash);border-radius:8px;padding:10px 14px}.toolbar{display:flex;flex-wrap:wrap;gap:12px;align-items:end;position:sticky;top:0;z-index:2}.control{display:grid;gap:4px}.control.grow{flex:1;min-width:220px}input,select{font:inherit;padding:8px 10px;border:1px solid #aeb9c7;border-radius:6px;background:white;color:var(--ink)}.group{padding:18px;margin:16px 0}.group>h2{border-bottom:1px solid var(--line);padding-bottom:10px}.card{padding:16px;margin:12px 0}.card-head{display:flex;gap:12px;align-items:flex-start;justify-content:space-between}.badge{display:inline-block;border-radius:100px;background:#e9f0fb;color:#183e71;padding:3px 9px;font-size:.83rem;font-weight:650}.confidence{color:var(--amber);font-size:.9rem;font-weight:650}.meta{display:flex;gap:8px 16px;flex-wrap:wrap;margin:10px 0;color:var(--muted);font-size:.92rem}.card h4{margin:12px 0 4px}.card ul{margin:4px 0 12px;padding-left:22px}.card a{color:var(--blue)}.coverage summary{cursor:pointer;font-weight:650}.coverage li{margin:6px 0}.empty{padding:20px;text-align:center;color:var(--muted)}.notice{border-left:4px solid #d39219;padding:8px 12px;background:#fff7e6;margin:12px 0}
+</style>
+</head>
+<body><main>
+<header class="intro"><h1>Customization review</h1><p>${escapeHtml(view.label || view.run_id)} · ${escapeHtml(view.instance)}</p><p class="muted">Status: ${escapeHtml(view.status)}. This report gives review steps, not automatic fixes. Confirm evidence before changing records.</p><div class="stats" id="stats"></div><p class="notice">A historical upgrade skip does not prove a current difference. A scope or updater name does not prove ownership. The broad metadata source is a bounded sample.</p></header>
+<section class="toolbar" aria-label="Report filters"><label class="control grow">Search artifacts<input id="search" type="search" placeholder="Name, table, scope, updater, evidence"></label><label class="control">Classification<select id="category"><option value="">All classifications</option>${categoryOptions}</select></label><label class="control">Group by<select id="group-by"><option value="type">File type</option><option value="scope">Scope</option><option value="updated_by">Updated by</option></select></label></section>
+<section id="results" aria-live="polite"></section>
+<details class="coverage"><summary>Capture coverage and limitations</summary><div id="coverage-content"></div></details>
+<script id="report-data" type="application/json">${data}</script>
+<script>
+'use strict';
+const report=JSON.parse(document.getElementById('report-data').textContent);
+const results=document.getElementById('results');
+const search=document.getElementById('search');
+const category=document.getElementById('category');
+const groupBy=document.getElementById('group-by');
+const el=(tag,text,className='')=>{const node=document.createElement(tag);if(text!==undefined)node.textContent=text;if(className)node.className=className;return node;};
+const groupName=item=>groupBy.value==='scope'?item.scope:groupBy.value==='updated_by'?item.updated_by:item.table_label;
+const addList=(parent,title,items)=>{parent.append(el('h4',title));const ul=el('ul');for(const text of items)ul.append(el('li',text));parent.append(ul);};
+function card(item){
+ const article=el('article',undefined,'card');const head=el('div',undefined,'card-head');const title=el('h3',item.name);head.append(title,el('span',item.triage.confidence,'confidence'));article.append(head);
+ article.append(el('p',item.triage.summary));const meta=el('div',undefined,'meta');meta.append(el('span',item.table_label+' · '+(item.identity.sys_id||'ID unavailable')),el('span','Scope: '+item.scope),el('span','Updated by: '+item.updated_by));article.append(meta,el('span',item.category_label,'badge'));
+ addList(article,'Evidence',item.evidence.length?item.evidence.map(e=>e.source+': '+e.sys_id+'. '+e.basis):['No artifact evidence was captured.']);addList(article,'Next steps',item.triage.next_steps);article.append(el('p','Risk: '+(item.risk.rating||'unknown')+'. '+(item.risk.rationale||'Not established.')));
+ if(item.record_url){const link=el('a','Open record in ServiceNow');link.href=item.record_url;link.rel='noopener noreferrer';link.target='_blank';article.append(link);}return article;
+}
+function render(){
+ const term=search.value.trim().toLowerCase();const selected=category.value;
+ const filtered=report.artifacts.filter(item=>(!selected||item.category===selected)&&(!term||JSON.stringify(item).toLowerCase().includes(term)));
+ results.replaceChildren();if(!filtered.length){results.append(el('p','No artifacts match these filters.','empty'));return;}
+ const groups=new Map();for(const item of filtered){const key=groupName(item);if(!groups.has(key))groups.set(key,[]);groups.get(key).push(item);}
+ for(const [name,items] of [...groups].sort(([a],[b])=>a.localeCompare(b))){const section=el('section',undefined,'group');section.append(el('h2',name+' ('+items.length+')'));for(const item of items)section.append(card(item));results.append(section);}
+}
+for(const [categoryName,items] of Object.entries(report.artifacts.reduce((groups,item)=>{groups[item.category]=(groups[item.category]||0)+1;return groups;},{})))document.getElementById('stats').append(el('span',categoryName.replaceAll('_',' ')+': '+items,'stat'));
+search.addEventListener('input',render);category.addEventListener('change',render);groupBy.addEventListener('change',render);render();
+const coverage=document.getElementById('coverage-content');const ul=el('ul');for(const [source,details] of Object.entries(report.coverage.sources||{})){ul.append(el('li',source+': '+details.status+', '+details.fetched+'/'+(details.available??'unknown')+' rows. '+details.reason));}coverage.append(ul);for(const note of report.coverage.limitations||[])coverage.append(el('p',note));
+</script>
+</main></body></html>\n`;
+}
+
+export function writeCustomizationHtml(report, { out } = {}) {
+  const runId = String(report.run_id || 'capture').replace(/[^a-zA-Z0-9_-]/g, '_');
+  const target = path.resolve(out || path.join(process.cwd(), `customizations-${runId}.html`));
+  fs.writeFileSync(target, renderCustomizationHtml(report), { mode: 0o600, flag: 'wx' });
+  return target;
+}