@jacebenson/jsn 4.3.13-dev.77.1 → 4.3.13-dev.79.1

package/package.json

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

package/src/app.js

@@ -16,7 +16,7 @@ import { resolveSession, applySession, contextFromSession, requireSessionInstanc
 import { getCurrentUser, getCurrentApplication, getCurrentUpdateSet } from './context.js';
 import { errUsage, errAuth } from './errors.js';
 import { canPrompt } from './helpers.js';
-import { isMutationCommand } from './mutations.js';
+import { guardMutationContext } from './mutation-context.js';
 import process from 'node:process';
 
 
@@ -78,7 +78,7 @@ export class App {
     return this.session?.instance || '';
   }
 
-  async printContextHeader(argv = {}) {
+  async printContextHeader(_argv = {}) {
     if (!this.getEffectiveInstance() || !this.sdk) return;
     if (process.env.JSN_NO_HEADER) return;
     if (this.output.getFormat() === FormatJSON || this.output.getFormat() === FormatQuiet) return;
@@ -104,12 +104,12 @@ export class App {
 
     // Both lookups depend on the user, but not on one another.
     const [application, selectedUpdateSet] = userSysID ? await Promise.all([
-      getCurrentApplication(this.sdk, userSysID).catch(() => null),
+      getCurrentApplication(this.sdk, userSysID, { unknownWhenMissing: true }).catch(() => null),
       getCurrentUpdateSet(this.sdk, userSysID).catch(() => null),
     ]) : [null, null];
-    const scope = application?.scope || 'global';
+    const scope = application?.scope || 'unknown';
     const updateSet = selectedUpdateSet?.name && selectedUpdateSet.name !== '-'
-      ? selectedUpdateSet.name : 'Default';
+      ? selectedUpdateSet.name : 'unknown';
     const updateSetSysID = selectedUpdateSet?.name && selectedUpdateSet.name !== '-'
       ? selectedUpdateSet.sys_id : '';
     this.context.scope = scope;
@@ -139,43 +139,14 @@ export class App {
 
     process.stderr.write(`${profileStr} ${userStr} ${scopeStr} ${updateSetStr}\n\n`);
 
-    // ⚠️  Warning if in the Default update set (mutation commands only)
-    if (isMutationCommand(argv) && updateSet && updateSet.toLowerCase().includes('default')) {
-      const isGlobal = scope === 'global';
-      if (isGlobal) {
-        // 🔴 HARD WARNING — Global + Default
-        process.stderr.write(
-          '\x1b[31m' + // red
-          '┏━ GLOBAL + DEFAULT ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓\n' +
-          '┃  You are in Global scope with the Default update set.  ┃\n' +
-          '┃  Changes ARE captured — in the Default update set.     ┃\n' +
-          '┃  Moving them to a named update set later requires      ┃\n' +
-          '┃  manual surgery, one change at a time. Avoid the mess. ┃\n' +
-          '┃                                                        ┃\n' +
-          '┃  Create a named update set now:                        ┃\n' +
-          '┃    jsn updatesets create --name "My Feature"       ┃\n' +
-          '┃                                                        ┃\n' +
-          '┃  Or switch to a scoped scope first:                    ┃\n' +
-          '┃    jsn scopes list                                 ┃\n' +
-          '┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛\x1b[0m\n'
-        );
-      } else {
-        // 🟡 SOFT WARNING — Scope + Default
-        process.stderr.write(
-          '\x1b[33m' + // yellow
-          '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n' +
-          '  ⚠  Default update set in scope [' + scope + ']\n' +
-          '  Changes are contained to this scope, but a named\n' +
-          '  update set is still recommended for tracking.\n' +
-          '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n' +
-          '\x1b[0m' // reset
-        );
-      }
-    }
+  }
+
+  async guardMutationContext(argv) {
+    this.mutationContext = await guardMutationContext(this, argv);
   }
 
   ok(data, opts = {}) {
-    this.output.ok(data, opts);
+    this.output.ok(data, this.mutationContext ? { ...opts, context: { ...opts.context, mutation: this.mutationContext } } : opts);
   }
 
   err(error) {

package/src/capabilities.js

@@ -16,6 +16,10 @@
 //     skipDailyChecks: true,
 //     // Suppress the current instance header for profile management commands.
 //     skipContextHeader: true,
+//     // Remediation commands bypass mutation capture-context approval only.
+//     mutationContextExemptSubcommands: ['create', 'set'],
+//     // REST methods that are reads (read-only profile policy is separate).
+//     mutationContextReadMethods: ['GET', 'HEAD', 'OPTIONS'],
 //   }
 //
 // cli.js derives every skip-list and the mutation guard's path list from

package/src/cli.js

@@ -117,6 +117,7 @@ function wrap(handler) {
         process.stderr.write('Error: App context not initialized.\n');
         process.exit(1);
       }
+      await app.guardMutationContext(argv);
       await handler(argv, app);
     } catch (err) {
       // All error rendering goes through the unified renderer in
@@ -145,6 +146,10 @@ export function buildCLI() {
       },
     ])
     .options({
+      force: {
+        type: 'boolean',
+        description: 'Approve Global + Default mutation context only after user approval; delete commands also use this for their separate confirmation',
+      },
       instance: {
         type: 'string',
         description: 'ServiceNow instance URL',

package/src/commands/rest.js

@@ -2,7 +2,7 @@ import { declareCapabilities } from '../capabilities.js';
 
 // Raw REST passthrough — can hit any endpoint with any method, so the whole
 // command is a mutation surface on read-only profiles.
-declareCapabilities('rest', { mutationSubcommands: [''] });
+declareCapabilities('rest', { mutationSubcommands: [''], mutationContextReadMethods: ['GET', 'HEAD', 'OPTIONS'] });
 
 export function restCmd(wrap) {
   return {

package/src/commands/scopes.js

@@ -3,7 +3,7 @@ import { requireCurrentUserSysId, setCurrentApplication } from '../context.js';
 import { declareCapabilities } from '../capabilities.js';
 import { unwrapSysId } from '../resolve-record.js';
 
-declareCapabilities('scopes', { mutationSubcommands: ['create', 'set'] });
+declareCapabilities('scopes', { mutationSubcommands: ['create', 'set'], mutationContextExemptSubcommands: ['create', 'set'] });
 
 /**
  * Resolve a scope identifier to a single sys_scope record.

package/src/commands/updatesets.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import { editor, confirm } from '../prompts.js';
-import { formatRecordForDisplay, getStringField, interactiveList, assertSafeExactMatch, canPrompt, buildRerunCommand, verifyWriteBack } from '../helpers.js';
+import { formatRecordForDisplay, getStringField, interactiveList, assertSafeExactMatch, canPrompt, buildRerunCommand, verifyWriteBack, quoteShellArg } from '../helpers.js';
 import { getActiveProfile } from '../config.js';
 import { FormatAuto } from '../output.js';
 import { getCurrentApplication, getCurrentUpdateSet, requireCurrentUserSysId, setCurrentApplication, setCurrentUpdateSet } from '../context.js';
@@ -11,6 +11,7 @@ import { unwrapSysId } from '../resolve-record.js';
 
 declareCapabilities('updatesets', {
   mutationSubcommands: ['create', 'set', 'complete', 'ignore', 'parent'],
+  mutationContextExemptSubcommands: ['create', 'set'],
 });
 
 /**
@@ -27,7 +28,7 @@ export function scopeMismatchWarning(updateSetApp, currentApp) {
   const updateSetAppId = updateSetApp?.value || (typeof updateSetApp === 'string' ? updateSetApp : '');
   if (!updateSetAppId || !currentApp.appSysId || updateSetAppId === currentApp.appSysId) return '';
   const name = updateSetApp?.display_value || updateSetApp;
-  return ` ⚠️ update set is in app "${name}", but current app is "${currentApp.scope}" — changes won't land here. Run: jsn scopes set ${name}`;
+  return ` ⚠️ update set is in app "${name}", but current app is "${currentApp.scope}" — changes may not be captured in this set. Run: jsn scopes set ${quoteShellArg(updateSetAppId)}`;
 }
 
 /** Format a picker label for an update set: "Name [State] (app/scope)". */
@@ -424,7 +425,7 @@ export function updateSetsCmd(wrap) {
   return {
     command: 'updatesets [subcommand]',
     aliases: ['updateset', 'us'],
-    describe: 'Manage update sets',
+    describe: 'Manage update sets. Global + Default mutations require approval (--force only after user approval); create/set remain available to select a dedicated capture set. Scope mismatches warn; completed capture sets block writes.',
     builder: (yargs) => {
       return yargs
         .command({

package/src/context.js

@@ -18,26 +18,26 @@ export async function getCurrentUser(sdk) {
   };
 }
 
-export async function getCurrentApplication(sdk, userSysID) {
+export async function getCurrentApplication(sdk, userSysID, { unknownWhenMissing = false } = {}) {
   const params = new URLSearchParams();
   params.set('sysparm_query', `user=${userSysID}^name=apps.current_app`);
   params.set('sysparm_limit', '1');
   params.set('sysparm_fields', 'value');
   const records = await sdk.list('sys_user_preference', params);
-  if (records.length === 0) return { scope: 'global', appSysId: '' };
+  if (records.length === 0) return { scope: unknownWhenMissing ? '' : 'global', appSysId: '' };
   const val = records[0].value?.value || records[0].value;
-  if (!val) return { scope: 'global', appSysId: '' };
+  if (!val) return { scope: unknownWhenMissing ? '' : 'global', appSysId: '' };
 
   // Try to resolve sys_id to scope name
   try {
     const app = await sdk.get('sys_scope', val);
-    if (app) return { scope: app.scope || 'global', appSysId: val };
+    if (app) return { scope: getStringField(app, 'scope') || (unknownWhenMissing ? '' : 'global'), appSysId: val };
   } catch {
     // fallback
   }
   try {
     const app2 = await sdk.get('sys_app', val);
-    if (app2) return { scope: app2.scope || 'global', appSysId: val };
+    if (app2) return { scope: getStringField(app2, 'scope') || (unknownWhenMissing ? '' : 'global'), appSysId: val };
   } catch {
     // fallback
   }
@@ -56,7 +56,7 @@ export async function getCurrentUpdateSet(sdk, userSysID) {
 
   try {
     const us = await sdk.get('sys_update_set', val);
-    if (us) return { name: us.name || val, sys_id: val };
+    if (us) return { name: getStringField(us, 'name') || val, sys_id: val, application: us.application, state: getStringField(us, 'state') };
   } catch {
     // fallback
   }

package/src/errors.js

@@ -213,7 +213,7 @@ export function isErrorCode(err, code) {
  * back to argv.format for callers without an App (unit tests).
  */
 function resolveJsonMode(app, argv) {
-  if (app?.output) return app.output.effectiveFormat() === 'json';
+  if (app?.output) return ['json', 'quiet'].includes(app.output.effectiveFormat());
   return argv?.format === 'json';
 }
 

package/src/mutation-context.js

@@ -0,0 +1,74 @@
+// Capture-context approval is independent of delete confirmation preferences.
+import process from 'node:process';
+import { collectCapabilities } from './capabilities.js';
+import { isMutationCommand } from './mutations.js';
+import { getCurrentUser, getCurrentApplication, getCurrentUpdateSet } from './context.js';
+import { canUsePicker, getStringField, quoteShellArg } from './helpers.js';
+import { confirm } from './prompts.js';
+import { AppError, CodeConfirmationRequired, errUsageHint } from './errors.js';
+
+export function needsMutationContext(argv) {
+  if (!isMutationCommand(argv)) return false;
+  const caps = collectCapabilities().get(argv._?.[0]) || {};
+  if (caps.mutationContextReadMethods?.includes(String(argv.method || 'GET').toUpperCase())) return false;
+  return !caps.mutationContextExemptSubcommands?.some(sub =>
+    sub.split(' ').every((part, index) => argv._?.[index + 1] === part));
+}
+
+function diagnostic(code, message, command, severity = 'warning') {
+  return { code, severity, message, remediation: { command } };
+}
+
+export async function guardMutationContext(app, argv, { ask = confirm, rawArgs = process.argv.slice(2) } = {}) {
+  if (!needsMutationContext(argv) || !app.sdk) return null;
+  let application, updateSet;
+  try {
+    const user = await getCurrentUser(app.sdk);
+    if (user?.sys_id) [application, updateSet] = await Promise.all([
+      getCurrentApplication(app.sdk, user.sys_id, { unknownWhenMissing: true }),
+      getCurrentUpdateSet(app.sdk, user.sys_id),
+    ]);
+  } catch {
+    // Failed reads are unknown context, never evidence of Global + Default.
+  }
+  const context = { scope: application?.scope || null, application_id: application?.appSysId || null,
+    update_set: updateSet ? { name: updateSet.name, sys_id: updateSet.sys_id, state: updateSet.state || null } : null,
+    diagnostics: [], approval_required: false, approved: false };
+  if (!context.scope || !updateSet) context.diagnostics.push(diagnostic('capture_context_unknown',
+    'Capture context could not be determined. Identify the intended scope and update set before development changes.', 'jsn updatesets list'));
+  const appId = getStringField(updateSet || {}, 'application');
+  const rawAppId = updateSet?.application?.value || appId;
+  if (application?.appSysId && rawAppId && application.appSysId !== rawAppId) {
+    context.diagnostics.push(diagnostic('update_set_scope_mismatch',
+      `Selected scope ${context.scope} and update set ${updateSet.name} belong to different applications; changes may not be captured in this set.`,
+      `jsn scopes set ${quoteShellArg(rawAppId)}`));
+  }
+  if (updateSet?.state && !['in progress', 'in_progress'].includes(updateSet.state.toLowerCase())) {
+    context.diagnostics.push(diagnostic('update_set_not_in_progress', `Selected update set ${updateSet.name} is ${updateSet.state}; select an in-progress capture set.`, 'jsn updatesets set', 'error'));
+    const error = errUsageHint('Selected capture update set is not in progress.', 'Run: jsn updatesets set');
+    error.context = context; throw error;
+  }
+  const globalDefault = context.scope?.toLowerCase() === 'global' && updateSet?.name?.toLowerCase() === 'default';
+  if (globalDefault) {
+    context.approval_required = true;
+    context.diagnostics.push(diagnostic('global_default_update_set',
+      'Global scope + Default update set can capture customization in the wrong place or leave changes untracked. Select or create a dedicated update set; not all record changes are update-set tracked.',
+      'jsn updatesets create --name "My Feature"'));
+    if (argv.force) context.approved = true;
+    else if (canUsePicker(app, argv)) {
+      context.approved = await ask({ message: `Scope: Global; update set: Default. ${context.diagnostics.at(-1).message} Approve this exact mutation: ${['jsn', ...rawArgs].map(quoteShellArg).join(' ')}?`, default: false });
+    }
+    if (!context.approved) {
+      const target = app.session?.profileName ? ` --profile ${quoteShellArg(app.session.profileName)}` : '';
+      const rerun = ['jsn', ...rawArgs.filter(arg => arg !== '--force')].map(quoteShellArg).join(' ') + (rawArgs.includes('--profile') ? '' : target);
+      const error = new AppError(CodeConfirmationRequired, 'Mutation in Global scope + Default update set requires explicit approval.',
+        `Select a dedicated set: jsn updatesets set; or jsn updatesets create --name "My Feature". Ask the user to approve this exact operation, then rerun: ${rerun} --force`);
+      error.context = context; throw error;
+    }
+  }
+  if (canUsePicker(app, argv)) {
+    process.stderr.write(`Mutation context: scope ${context.scope || 'unknown'}; update set ${updateSet?.name || 'unknown'}${updateSet?.sys_id ? ` (${updateSet.sys_id})` : ''}.\n`);
+    for (const item of context.diagnostics) process.stderr.write(`Warning (${item.code}): ${item.message} Run: ${item.remediation.command}\n`);
+  }
+  return context;
+}

package/src/output.js

@@ -160,6 +160,7 @@ export class OutputWriter {
     const format = this.effectiveFormat();
     const e = error.code ? error : { code: 'unknown', message: String(error), hint: '' };
     const resp = { ok: false, error: e.message, code: e.code, hint: e.hint || '' };
+    if (e.context) resp.context = e.context;
     if (e.status === 401 || e.status === 403) resp.status = e.status;
     if (e.recovery) {
       resp.recovery = e.recovery;